annotate lispintro/emacs-lisp-intro.texi @ 42251:d2e8e0db6666

(ange-ftp-file-modtime): Use save-match-data.
author Richard M. Stallman <rms@gnu.org>
date Fri, 21 Dec 2001 23:57:20 +0000
parents 24f8e84cb04d
children d918430979ea
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1 \input texinfo @c -*-texinfo-*-
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2 @comment %**start of header
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3 @setfilename ../info/eintr
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4 @c sethtmlfilename emacs-lisp-intro.html
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5 @settitle Programming in Emacs Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6 @syncodeindex vr cp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7 @syncodeindex fn cp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8 @setchapternewpage odd
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9 @finalout
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11 @c ---------
41499
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
12 @c <<<< For hard copy printing, this file is now
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
13 @c set for smallbook, which works for all sizes
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
14 @c of paper, and with Postscript figures >>>>
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
15 @smallbook
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
16 @clear largebook
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17 @set print-postscript-figures
41499
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
18 @c set largebook
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
19 @c clear print-postscript-figures
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20 @c ---------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
22 @comment %**end of header
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
23
42108
dcab51f5352e Define `empty string' a second time, in a slightly more visible location.
Robert J. Chassell <bob@rattlesnake.com>
parents: 41872
diff changeset
24 @set edition-number 2.04
dcab51f5352e Define `empty string' a second time, in a slightly more visible location.
Robert J. Chassell <bob@rattlesnake.com>
parents: 41872
diff changeset
25 @set update-date 2001 Dec 17
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
26
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
27 @ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
28 ## Summary of shell commands to create various output formats:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
29
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
30 ## Info output
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
31 makeinfo --no-split --paragraph-indent=0 --verbose emacs-lisp-intro.texi
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
32
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
33 ## DVI output
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
34 texi2dvi emacs-lisp-intro.texi
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
35
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
36 ## HTML output
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
37 makeinfo --html --no-split --verbose emacs-lisp-intro.texi
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
38
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
39 ## Plain text output
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
40 makeinfo --fill-column=70 --no-split --paragraph-indent=0 \
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
41 --verbose --no-headers --output=emacs-lisp-intro.txt emacs-lisp-intro.texi
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
42
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
43 @end ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
44
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
45 @c ================ Included Figures ================
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
46
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
47 @c Set print-postscript-figures if you print PostScript figures.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
48 @c If you clear this, the ten figures will be printed as ASCII diagrams.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
49 @c (This is not relevant to Info, since Info only handles ASCII.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
50 @c Your site may require editing changes to print PostScript; in this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
51 @c case, search for `print-postscript-figures' and make appropriate changes.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
52
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
53
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
54 @c ================ How to Create an Info file ================
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
55
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
56 @c If you have `makeinfo' installed, run the following command
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
57
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
58 @c makeinfo emacs-lisp-intro.texi
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
59
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
60 @c or, if you want a single, large Info file, and no paragraph indents:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
61 @c makeinfo --no-split --paragraph-indent=0 --verbose emacs-lisp-intro.texi
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
62
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
63 @c After creating the Info file, edit your Info `dir' file, if the
41674
ea1354316d4f Fixed typographic error.
Robert J. Chassell <bob@rattlesnake.com>
parents: 41670
diff changeset
64 @c `dircategory' section below does not enable your system to
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
65 @c install the manual automatically.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
66 @c (The `dir' file is often in the `/usr/local/info/' directory.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
67
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
68 @c ================ How to Create an HTML file ================
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
69
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
70 @c To convert to HTML format
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
71 @c makeinfo --html --no-split --verbose emacs-lisp-intro.texi
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
72
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
73 @c ================ How to Print a Book in Various Sizes ================
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
74
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
75 @c This book can be printed in any of three different sizes.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
76 @c In the above header, set @-commands appropriately.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
77
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
78 @c 7 by 9.25 inches:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
79 @c @smallbook
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
80 @c @clear largebook
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
81
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
82 @c 8.5 by 11 inches:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
83 @c @c smallbook
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
84 @c @set largebook
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
85
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
86 @c European A4 size paper:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
87 @c @c smallbook
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
88 @c @afourpaper
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
89 @c @set largebook
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
90
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
91 @c ================ How to Typeset and Print ================
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
92
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
93 @c If you do not include PostScript figures, run either of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
94 @c following command sequences, or similar commands suited to your
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
95 @c system:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
96
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
97 @c texi2dvi emacs-lisp-intro.texi
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
98 @c lpr -d emacs-lisp-intro.dvi
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
99
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
100 @c or else:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
101
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
102 @c tex emacs-lisp-intro.texi
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
103 @c texindex emacs-lisp-intro.??
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
104 @c tex emacs-lisp-intro.texi
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
105 @c lpr -d emacs-lisp-intro.dvi
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
106
41499
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
107 @c If you include the PostScript figures, and you have old software,
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
108 @c you may need to convert the .dvi file to a .ps file before
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
109 @c printing. Run either of the following command sequences, or one
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
110 @c similar:
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
111 @c
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
112 @c dvips -f < emacs-lisp-intro.dvi > emacs-lisp-intro.ps
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
113 @c
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
114 @c or else:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
115 @c
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
116 @c postscript -p < emacs-lisp-intro.dvi > emacs-lisp-intro.ps
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
117 @c
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
118
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
119 @c (Note: if you edit the book so as to change the length of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
120 @c table of contents, you may have to change the value of `pageno' below.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
121
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
122 @c ================ End of Formatting Sections ================
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
123
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
124 @c For next or subsequent edition:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
125 @c create function using with-output-to-temp-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
126 @c create a major mode, with keymaps
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
127 @c run an asynchronous process, like grep or diff
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
128
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
129 @c For smallbook format, use smaller than normal amounts of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
130 @c whitespace between chapters, sections, and paragraphs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
131 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
132 \global\chapheadingskip = 15pt plus 4pt minus 2pt
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
133 \global\secheadingskip = 12pt plus 3pt minus 2pt
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
134 \global\subsecheadingskip = 9pt plus 2pt minus 2pt \global\parskip 2pt
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
135 plus 1pt
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
136 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
137
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
138 @c For 8.5 by 11 inch format: do not use such a small amount of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
139 @c whitespace between paragraphs as above:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
140 @ifset largebook
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
141 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
142 \global\parskip 6pt plus 1pt
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
143 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
144 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
145
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
146 @c For all sized formats: print within-book cross
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
147 @c reference with ``...'' rather than [...]
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
148 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
149 % Need following so comma appears after section numbers.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
150 \global\def\Ysectionnumberandtype{%
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
151 \ifnum\secno=0 \putwordChapter\xreftie\the\chapno, \space %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
152 \else \ifnum \subsecno=0 \putwordSection\xreftie\the\chapno.\the\secno, \space %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
153 \else \ifnum \subsubsecno=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
154 \putwordSection\xreftie\the\chapno.\the\secno.\the\subsecno, \space %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
155 \else %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
156 \putwordSection\xreftie\the\chapno.\the\secno.\the\subsecno.\the\subsubsecno, \space%
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
157 \fi \fi \fi }
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
158
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
159 \global\def\Yappendixletterandtype{%
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
160 \ifnum\secno=0 \putwordAppendix\xreftie'char\the\appendixno{}, \space%
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
161 \else \ifnum \subsecno=0 \putwordSection\xreftie'char\the\appendixno.\the\secno, \space %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
162 \else \ifnum \subsubsecno=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
163 \putwordSection\xreftie'char\the\appendixno.\the\secno.\the\subsecno, \space %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
164 \else %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
165 \putwordSection\xreftie'char\the\appendixno.\the\secno.\the\subsecno.\the\subsubsecno, \space %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
166 \fi \fi \fi }
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
167
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
168 \global\def\xrefX[#1,#2,#3,#4,#5,#6]{\begingroup
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
169 \def\printedmanual{\ignorespaces #5}%
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
170 \def\printednodename{\ignorespaces #3}%
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
171 \setbox1=\hbox{\printedmanual}%
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
172 \setbox0=\hbox{\printednodename}%
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
173 \ifdim \wd0 = 0pt
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
174 % No printed node name was explicitly given.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
175 \ifx\SETxref-automatic-section-title\relax %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
176 % Use the actual chapter/section title appear inside
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
177 % the square brackets. Use the real section title if we have it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
178 \ifdim \wd1>0pt%
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
179 % It is in another manual, so we don't have it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
180 \def\printednodename{\ignorespaces #1}%
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
181 \else
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
182 \ifhavexrefs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
183 % We know the real title if we have the xref values.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
184 \def\printednodename{\refx{#1-title}}%
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
185 \else
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
186 % Otherwise just copy the Info node name.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
187 \def\printednodename{\ignorespaces #1}%
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
188 \fi%
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
189 \fi
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
190 \def\printednodename{#1-title}%
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
191 \else
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
192 % Use the node name inside the square brackets.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
193 \def\printednodename{\ignorespaces #1}%
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
194 \fi
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
195 \fi
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
196 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
197 % If we use \unhbox0 and \unhbox1 to print the node names, TeX does not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
198 % insert empty discretionaries after hyphens, which means that it will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
199 % not find a line break at a hyphen in a node names. Since some manuals
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
200 % are best written with fairly long node names, containing hyphens, this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
201 % is a loss. Therefore, we give the text of the node name again, so it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
202 % is as if TeX is seeing it for the first time.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
203 \ifdim \wd1 > 0pt
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
204 \putwordsection{} ``\printednodename'' in \cite{\printedmanual}%
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
205 \else
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
206 % _ (for example) has to be the character _ for the purposes of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
207 % control sequence corresponding to the node, but it has to expand
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
208 % into the usual \leavevmode...\vrule stuff for purposes of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
209 % printing. So we \turnoffactive for the \refx-snt, back on for the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
210 % printing, back off for the \refx-pg.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
211 {\turnoffactive \refx{#1-snt}{}}%
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
212 % \space [\printednodename],\space % <= original
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
213 % \putwordsection{} ``\printednodename'',\space
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
214 ``\printednodename'',\space
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
215 \turnoffactive \putwordpage\tie\refx{#1-pg}{}%
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
216 \fi
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
217 \endgroup}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
218 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
219
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
220 @c ----------------------------------------------------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
221
41670
b4c633081255 (Index): @ignore extraneous text.
Eli Zaretskii <eliz@gnu.org>
parents: 41499
diff changeset
222 @dircategory Emacs
b4c633081255 (Index): @ignore extraneous text.
Eli Zaretskii <eliz@gnu.org>
parents: 41499
diff changeset
223 @direntry
b4c633081255 (Index): @ignore extraneous text.
Eli Zaretskii <eliz@gnu.org>
parents: 41499
diff changeset
224 * Emacs Lisp Intro: (eintr).
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
225 A simple introduction to Emacs Lisp programming.
41670
b4c633081255 (Index): @ignore extraneous text.
Eli Zaretskii <eliz@gnu.org>
parents: 41499
diff changeset
226 @end direntry
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
227
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
228 @ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
229 This is an introduction to @cite{Programming in Emacs Lisp}, for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
230 people who are not programmers.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
231
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
232 Edition @value{edition-number}, @value{update-date}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
233
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
234 Copyright (C) 1990, '91, '92, '93, '94, '95, '97, 2001 Free Software Foundation, Inc.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
235
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
236 Permission is granted to copy, distribute and/or modify this document
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
237 under the terms of the GNU Free Documentation License, Version 1.1 or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
238 any later version published by the Free Software Foundation; with the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
239 Invariant Section being the Preface, with the Front-Cover Texts being
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
240 no Front-Cover Texts, and with the Back-Cover Texts being no
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
241 Back-Cover Texts. A copy of the license is included in the section
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
242 entitled ``GNU Free Documentation License''.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
243 @end ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
244
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
245 @c half title; two lines here, so do not use `shorttitlepage'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
246 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
247 {\begingroup%
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
248 \hbox{}\vskip 1.5in \chaprm \centerline{An Introduction to}%
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
249 \endgroup}%
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
250 {\begingroup\hbox{}\vskip 0.25in \chaprm%
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
251 \centerline{Programming in Emacs Lisp}%
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
252 \endgroup\page\hbox{}\page}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
253 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
254
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
255 @titlepage
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
256 @sp 6
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
257 @center @titlefont{An Introduction to}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
258 @sp 2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
259 @center @titlefont{Programming in Emacs Lisp}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
260 @sp 2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
261 @center Second Edition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
262 @sp 4
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
263 @center by Robert J. Chassell
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
264
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
265 @page
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
266 @vskip 0pt plus 1filll
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
267 Copyright @copyright{} 1990, '91, '92, '93, '94, '95, '97, 2001 Free Software Foundation, Inc.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
268 @sp 2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
269
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
270 Published by the Free Software Foundation, Inc.@*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
271 59 Temple Place, Suite 330@*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
272 Boston, MA 02111-1307 USA@*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
273
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
274 Edition @value{edition-number}, @value{update-date}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
275
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
276 @c Printed copies are available for $20 each.@*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
277 ISBN-1882114-41-8
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
278
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
279 Permission is granted to copy, distribute and/or modify this document
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
280 under the terms of the GNU Free Documentation License, Version 1.1 or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
281 any later version published by the Free Software Foundation; with the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
282 Invariant Section being the Preface, with the Front-Cover Texts being
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
283 no Front-Cover Texts, and with the Back-Cover Texts being no
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
284 Back-Cover Texts. A copy of the license is included in the section
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
285 entitled ``GNU Free Documentation License''.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
286 @end titlepage
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
287
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
288 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
289 @headings off
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
290 @evenheading @thispage @| @| @thischapter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
291 @oddheading @thissection @| @| @thispage
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
292 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
293
41499
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
294 @ifnothtml
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
295
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
296 @c Keep T.O.C. short by tightening up.
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
297 @ifset largebook
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
298 @tex
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
299 \global\parskip 2pt plus 1pt
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
300 \global\advance\baselineskip by -1pt
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
301 @end tex
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
302 @end ifset
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
303
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
304 @shortcontents
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
305 @contents
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
306
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
307 @ifset largebook
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
308 @tex
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
309 \global\parskip 6pt plus 1pt
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
310 \global\advance\baselineskip by 1pt
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
311 @end tex
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
312 @end ifset
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
313
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
314 @end ifnothtml
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
315
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
316 @c >>>> Set pageno appropriately <<<<
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
317
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
318 @c The first page of the Preface is a roman numeral; it is the first
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
319 @c right handed page after the Table of Contents; hence the following
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
320 @c setting must be for an odd negative number.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
321
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
322 @c if largebook, there are 8 pages in Table of Contents
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
323 @ifset largebook
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
324 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
325 @pageno = -9
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
326 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
327 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
328
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
329 @c if smallbook, there are 10 pages in Table of Contents
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
330 @ifclear largebook
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
331 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
332 @pageno = -11
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
333 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
334 @end ifclear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
335
41499
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
336 @ifnottex
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
337 @node Top, Preface, (dir), (dir)
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
338 @top An Introduction to Programming in Emacs Lisp
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
339
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
340 This is an introduction to @cite{Programming in Emacs Lisp}, for
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
341 people who are not programmers.
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
342
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
343 This master menu first lists each chapter and index; then it lists
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
344 every node in every chapter.
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
345 @end ifnottex
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
346
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
347 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
348 * Preface:: What to look for.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
349 * List Processing:: What is Lisp?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
350 * Practicing Evaluation:: Running several programs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
351 * Writing Defuns:: How to write function definitions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
352 * Buffer Walk Through:: Exploring a few buffer-related functions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
353 * More Complex:: A few, even more complex functions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
354 * Narrowing & Widening:: Restricting your and Emacs attention to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
355 a region.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
356 * car cdr & cons:: Fundamental functions in Lisp.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
357 * Cutting & Storing Text:: Removing text and saving it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
358 * List Implementation:: How lists are implemented in the computer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
359 * Yanking:: Pasting stored text.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
360 * Loops & Recursion:: How to repeat a process.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
361 * Regexp Search:: Regular expression searches.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
362 * Counting Words:: A review of repetition and regexps.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
363 * Words in a defun:: Counting words in a @code{defun}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
364 * Readying a Graph:: A prototype graph printing function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
365 * Emacs Initialization:: How to write a @file{.emacs} file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
366 * Debugging:: How to run the Emacs Lisp debuggers.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
367 * Conclusion:: Now you have the basics.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
368 * the-the:: An appendix: how to find reduplicated words.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
369 * Kill Ring:: An appendix: how the kill ring works.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
370 * Full Graph:: How to create a graph with labelled axes.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
371 * GNU Free Documentation License::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
372 * Index::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
373 * About the Author::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
374
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
375 @detailmenu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
376 --- The Detailed Node Listing ---
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
377
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
378 Preface
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
379
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
380 * Why:: Why learn Emacs Lisp?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
381 * On Reading this Text:: Read, gain familiarity, pick up habits....
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
382 * Who You Are:: For whom this is written.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
383 * Lisp History::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
384 * Note for Novices:: You can read this as a novice.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
385 * Thank You::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
386
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
387 List Processing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
388
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
389 * Lisp Lists:: What are lists?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
390 * Run a Program:: Any list in Lisp is a program ready to run.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
391 * Making Errors:: Generating an error message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
392 * Names & Definitions:: Names of symbols and function definitions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
393 * Lisp Interpreter:: What the Lisp interpreter does.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
394 * Evaluation:: Running a program.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
395 * Variables:: Returning a value from a variable.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
396 * Arguments:: Passing information to a function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
397 * set & setq:: Setting the value of a variable.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
398 * Summary:: The major points.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
399 * Error Message Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
400
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
401 Lisp Lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
402
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
403 * Numbers Lists:: List have numbers, other lists, in them.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
404 * Lisp Atoms:: Elemental entities.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
405 * Whitespace in Lists:: Formating lists to be readable.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
406 * Typing Lists:: How GNU Emacs helps you type lists.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
407
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
408 The Lisp Interpreter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
409
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
410 * Complications:: Variables, Special forms, Lists within.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
411 * Byte Compiling:: Specially processing code for speed.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
412
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
413 Evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
414
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
415 * Evaluating Inner Lists:: Lists within lists...
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
416
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
417 Variables
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
418
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
419 * fill-column Example::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
420 * Void Function:: The error message for a symbol
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
421 without a function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
422 * Void Variable:: The error message for a symbol without a value.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
423
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
424 Arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
425
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
426 * Data types:: Types of data passed to a function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
427 * Args as Variable or List:: An argument can be the value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
428 of a variable or list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
429 * Variable Number of Arguments:: Some functions may take a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
430 variable number of arguments.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
431 * Wrong Type of Argument:: Passing an argument of the wrong type
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
432 to a function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
433 * message:: A useful function for sending messages.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
434
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
435 Setting the Value of a Variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
436
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
437 * Using set:: Setting values.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
438 * Using setq:: Setting a quoted value.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
439 * Counting:: Using @code{setq} to count.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
440
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
441 Practicing Evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
442
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
443 * How to Evaluate:: Typing editing commands or @kbd{C-x C-e}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
444 causes evaluation.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
445 * Buffer Names:: Buffers and files are different.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
446 * Getting Buffers:: Getting a buffer itself, not merely its name.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
447 * Switching Buffers:: How to change to another buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
448 * Buffer Size & Locations:: Where point is located and the size of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
449 the buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
450 * Evaluation Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
451
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
452 How To Write Function Definitions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
453
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
454 * Primitive Functions::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
455 * defun:: The @code{defun} special form.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
456 * Install:: Install a function definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
457 * Interactive:: Making a function interactive.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
458 * Interactive Options:: Different options for @code{interactive}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
459 * Permanent Installation:: Installing code permanently.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
460 * let:: Creating and initializing local variables.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
461 * if:: What if?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
462 * else:: If--then--else expressions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
463 * Truth & Falsehood:: What Lisp considers false and true.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
464 * save-excursion:: Keeping track of point, mark, and buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
465 * Review::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
466 * defun Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
467
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
468 Install a Function Definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
469
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
470 * Effect of installation::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
471 * Change a defun:: How to change a function definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
472
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
473 Make a Function Interactive
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
474
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
475 * Interactive multiply-by-seven:: An overview.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
476 * multiply-by-seven in detail:: The interactive version.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
477
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
478 @code{let}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
479
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
480 * Prevent confusion::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
481 * Parts of let Expression::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
482 * Sample let Expression::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
483 * Uninitialized let Variables::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
484
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
485 The @code{if} Special Form
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
486
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
487 * if in more detail::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
488 * type-of-animal in detail:: An example of an @code{if} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
489
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
490 Truth and Falsehood in Emacs Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
491
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
492 * nil explained:: @code{nil} has two meanings.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
493
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
494 @code{save-excursion}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
495
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
496 * Point and mark:: A review of various locations.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
497 * Template for save-excursion::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
498
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
499 A Few Buffer--Related Functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
501 * Finding More:: How to find more information.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
502 * simplified-beginning-of-buffer:: Shows @code{goto-char},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
503 @code{point-min}, and @code{push-mark}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
504 * mark-whole-buffer:: Almost the same as @code{beginning-of-buffer}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
505 * append-to-buffer:: Uses @code{save-excursion} and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
506 @code{insert-buffer-substring}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
507 * Buffer Related Review:: Review.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
508 * Buffer Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
509
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
510 The Definition of @code{mark-whole-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
511
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
512 * mark-whole-buffer overview::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
513 * Body of mark-whole-buffer:: Only three lines of code.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
514
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
515 The Definition of @code{append-to-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
516
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
517 * append-to-buffer overview::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
518 * append interactive:: A two part interactive expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
519 * append-to-buffer body:: Incorporates a @code{let} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
520 * append save-excursion:: How the @code{save-excursion} works.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
521
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
522 A Few More Complex Functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
523
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
524 * copy-to-buffer:: With @code{set-buffer}, @code{get-buffer-create}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
525 * insert-buffer:: Read-only, and with @code{or}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
526 * beginning-of-buffer:: Shows @code{goto-char},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
527 @code{point-min}, and @code{push-mark}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
528 * Second Buffer Related Review::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
529 * optional Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
530
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
531 The Definition of @code{insert-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
532
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
533 * insert-buffer code::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
534 * insert-buffer interactive:: When you can read, but not write.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
535 * insert-buffer body:: The body has an @code{or} and a @code{let}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
536 * if & or:: Using an @code{if} instead of an @code{or}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
537 * Insert or:: How the @code{or} expression works.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
538 * Insert let:: Two @code{save-excursion} expressions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
539
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
540 The Interactive Expression in @code{insert-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
541
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
542 * Read-only buffer:: When a buffer cannot be modified.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
543 * b for interactive:: An existing buffer or else its name.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
544
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
545 Complete Definition of @code{beginning-of-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
546
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
547 * Optional Arguments::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
548 * beginning-of-buffer opt arg:: Example with optional argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
549 * beginning-of-buffer complete::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
550
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
551 @code{beginning-of-buffer} with an Argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
552
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
553 * Disentangle beginning-of-buffer::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
554 * Large buffer case::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
555 * Small buffer case::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
556
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
557 Narrowing and Widening
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
558
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
559 * Narrowing advantages:: The advantages of narrowing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
560 * save-restriction:: The @code{save-restriction} special form.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
561 * what-line:: The number of the line that point is on.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
562 * narrow Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
563
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
564 @code{car}, @code{cdr}, @code{cons}: Fundamental Functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
565
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
566 * Strange Names:: An historical aside: why the strange names?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
567 * car & cdr:: Functions for extracting part of a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
568 * cons:: Constructing a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
569 * nthcdr:: Calling @code{cdr} repeatedly.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
570 * nth::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
571 * setcar:: Changing the first element of a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
572 * setcdr:: Changing the rest of a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
573 * cons Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
574
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
575 @code{cons}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
576
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
577 * Build a list::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
578 * length:: How to find the length of a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
579
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
580 Cutting and Storing Text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
581
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
582 * Storing Text:: Text is stored in a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
583 * zap-to-char:: Cutting out text up to a character.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
584 * kill-region:: Cutting text out of a region.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
585 * Digression into C:: Minor note on C programming language macros.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
586 * defvar:: How to give a variable an initial value.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
587 * copy-region-as-kill:: A definition for copying text.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
588 * cons & search-fwd Review::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
589 * search Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
590
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
591 @code{zap-to-char}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
592
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
593 * Complete zap-to-char:: The complete implementation.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
594 * zap-to-char interactive:: A three part interactive expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
595 * zap-to-char body:: A short overview.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
596 * search-forward:: How to search for a string.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
597 * progn:: The @code{progn} special form.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
598 * Summing up zap-to-char:: Using @code{point} and @code{search-forward}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
599
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
600 @code{kill-region}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
601
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
602 * Complete kill-region:: The function definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
603 * condition-case:: Dealing with a problem.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
604 * delete-and-extract-region:: Doing the work.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
605
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
606 Initializing a Variable with @code{defvar}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
607
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
608 * See variable current value::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
609 * defvar and asterisk:: An old-time convention.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
610
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
611 @code{copy-region-as-kill}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
612
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
613 * Complete copy-region-as-kill:: The complete function definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
614 * copy-region-as-kill body:: The body of @code{copy-region-as-kill}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
615
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
616 The Body of @code{copy-region-as-kill}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
617
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
618 * last-command & this-command::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
619 * kill-append function::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
620 * kill-new function::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
621
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
622 How Lists are Implemented
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
623
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
624 * Lists diagrammed::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
625 * Symbols as Chest:: Exploring a powerful metaphor.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
626 * List Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
627
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
628 Yanking Text Back
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
629
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
630 * Kill Ring Overview:: The kill ring is a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
631 * kill-ring-yank-pointer:: The @code{kill-ring-yank-pointer} variable.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
632 * yank nthcdr Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
633
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
634 Loops and Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
635
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
636 * while:: Causing a stretch of code to repeat.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
637 * dolist dotimes::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
638 * Recursion:: Causing a function to call itself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
639 * Looping exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
640
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
641 @code{while}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
642
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
643 * Looping with while:: Repeat so long as test returns true.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
644 * Loop Example:: A @code{while} loop that uses a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
645 * print-elements-of-list:: Uses @code{while}, @code{car}, @code{cdr}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
646 * Incrementing Loop:: A loop with an incrementing counter.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
647 * Decrementing Loop:: A loop with a decrementing counter.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
648
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
649 A Loop with an Incrementing Counter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
650
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
651 * Incrementing Example:: Counting pebbles in a triangle.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
652 * Inc Example parts:: The parts of the function definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
653 * Inc Example altogether:: Putting the function definition together.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
654
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
655 Loop with a Decrementing Counter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
656
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
657 * Decrementing Example:: More pebbles on the beach.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
658 * Dec Example parts:: The parts of the function definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
659 * Dec Example altogether:: Putting the function definition together.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
660
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
661 Save your time: @code{dolist} and @code{dotimes}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
662
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
663 * dolist::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
664 * dotimes::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
665
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
666 Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
667
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
668 * Building Robots:: Same model, different serial number ...
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
669 * Recursive Definition Parts:: Walk until you stop ...
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
670 * Recursion with list:: Using a list as the test whether to recurse.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
671 * Recursive triangle function::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
672 * Recursion with cond::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
673 * Recursive Patterns:: Often used templates.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
674 * No Deferment:: Don't store up work ...
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
675 * No deferment solution::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
676
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
677 Recursion in Place of a Counter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
678
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
679 * Recursive Example arg of 1 or 2::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
680 * Recursive Example arg of 3 or 4::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
681
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
682 Recursive Patterns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
683
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
684 * Every::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
685 * Accumulate::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
686 * Keep::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
687
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
688 Regular Expression Searches
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
689
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
690 * sentence-end:: The regular expression for @code{sentence-end}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
691 * re-search-forward:: Very similar to @code{search-forward}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
692 * forward-sentence:: A straightforward example of regexp search.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
693 * forward-paragraph:: A somewhat complex example.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
694 * etags:: How to create your own @file{TAGS} table.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
695 * Regexp Review::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
696 * re-search Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
697
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
698 @code{forward-sentence}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
699
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
700 * Complete forward-sentence::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
701 * fwd-sentence while loops:: Two @code{while} loops.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
702 * fwd-sentence re-search:: A regular expression search.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
703
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
704 @code{forward-paragraph}: a Goldmine of Functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
705
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
706 * forward-paragraph in brief:: Key parts of the function definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
707 * fwd-para let:: The @code{let*} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
708 * fwd-para while:: The forward motion @code{while} loop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
709 * fwd-para between paragraphs:: Movement between paragraphs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
710 * fwd-para within paragraph:: Movement within paragraphs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
711 * fwd-para no fill prefix:: When there is no fill prefix.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
712 * fwd-para with fill prefix:: When there is a fill prefix.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
713 * fwd-para summary:: Summary of @code{forward-paragraph} code.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
714
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
715 Counting: Repetition and Regexps
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
716
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
717 * Why Count Words::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
718 * count-words-region:: Use a regexp, but find a problem.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
719 * recursive-count-words:: Start with case of no words in region.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
720 * Counting Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
721
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
722 The @code{count-words-region} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
723
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
724 * Design count-words-region:: The definition using a @code{while} loop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
725 * Whitespace Bug:: The Whitespace Bug in @code{count-words-region}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
726
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
727 Counting Words in a @code{defun}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
728
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
729 * Divide and Conquer::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
730 * Words and Symbols:: What to count?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
731 * Syntax:: What constitutes a word or symbol?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
732 * count-words-in-defun:: Very like @code{count-words}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
733 * Several defuns:: Counting several defuns in a file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
734 * Find a File:: Do you want to look at a file?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
735 * lengths-list-file:: A list of the lengths of many definitions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
736 * Several files:: Counting in definitions in different files.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
737 * Several files recursively:: Recursively counting in different files.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
738 * Prepare the data:: Prepare the data for display in a graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
739
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
740 Count Words in @code{defuns} in Different Files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
741
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
742 * lengths-list-many-files:: Return a list of the lengths of defuns.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
743 * append:: Attach one list to another.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
744
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
745 Prepare the Data for Display in a Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
746
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
747 * Sorting:: Sorting lists.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
748 * Files List:: Making a list of files.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
749 * Counting function definitions::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
750
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
751 Readying a Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
752
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
753 * Columns of a graph::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
754 * graph-body-print:: How to print the body of a graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
755 * recursive-graph-body-print::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
756 * Printed Axes::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
757 * Line Graph Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
758
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
759 Your @file{.emacs} File
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
760
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
761 * Default Configuration::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
762 * Site-wide Init:: You can write site-wide init files.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
763 * defcustom:: Emacs will write code for you.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
764 * Beginning a .emacs File:: How to write a @code{.emacs file}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
765 * Text and Auto-fill:: Automatically wrap lines.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
766 * Mail Aliases:: Use abbreviations for email addresses.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
767 * Indent Tabs Mode:: Don't use tabs with @TeX{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
768 * Keybindings:: Create some personal keybindings.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
769 * Keymaps:: More about key binding.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
770 * Loading Files:: Load (i.e., evaluate) files automatically.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
771 * Autoload:: Make functions available.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
772 * Simple Extension:: Define a function; bind it to a key.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
773 * X11 Colors:: Colors in version 19 in X.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
774 * Miscellaneous::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
775 * Mode Line:: How to customize your mode line.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
776
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
777 Debugging
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
778
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
779 * debug:: How to use the built-in debugger.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
780 * debug-on-entry:: Start debugging when you call a function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
781 * debug-on-quit:: Start debugging when you quit with @kbd{C-g}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
782 * edebug:: How to use Edebug, a source level debugger.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
783 * Debugging Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
784
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
785 Handling the Kill Ring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
786
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
787 * rotate-yank-pointer:: Move a pointer along a list and around.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
788 * yank:: Paste a copy of a clipped element.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
789 * yank-pop:: Insert first element pointed to.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
790
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
791 The @code{rotate-yank-pointer} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
792
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
793 * Understanding rotate-yk-ptr::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
794 * rotate-yk-ptr body:: The body of @code{rotate-yank-pointer}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
795
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
796 The Body of @code{rotate-yank-pointer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
797
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
798 * Digression concerning error:: How to mislead humans, but not computers.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
799 * rotate-yk-ptr else-part:: The else-part of the @code{if} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
800 * Remainder Function:: The remainder, @code{%}, function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
801 * rotate-yk-ptr remainder:: Using @code{%} in @code{rotate-yank-pointer}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
802 * kill-rng-yk-ptr last elt:: Pointing to the last element.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
803
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
804 @code{yank}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
805
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
806 * rotate-yk-ptr arg:: Pass the argument to @code{rotate-yank-pointer}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
807 * rotate-yk-ptr negative arg:: Pass a negative argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
808
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
809 A Graph with Labelled Axes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
810
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
811 * Labelled Example::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
812 * print-graph Varlist:: @code{let} expression in @code{print-graph}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
813 * print-Y-axis:: Print a label for the vertical axis.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
814 * print-X-axis:: Print a horizontal label.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
815 * Print Whole Graph:: The function to print a complete graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
816
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
817 The @code{print-Y-axis} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
818
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
819 * Height of label:: What height for the Y axis?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
820 * Compute a Remainder:: How to compute the remainder of a division.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
821 * Y Axis Element:: Construct a line for the Y axis.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
822 * Y-axis-column:: Generate a list of Y axis labels.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
823 * print-Y-axis Penultimate:: A not quite final version.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
824
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
825 The @code{print-X-axis} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
826
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
827 * Similarities differences:: Much like @code{print-Y-axis}, but not exactly.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
828 * X Axis Tic Marks:: Create tic marks for the horizontal axis.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
829
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
830 Printing the Whole Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
831
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
832 * The final version:: A few changes.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
833 * Test print-graph:: Run a short test.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
834 * Graphing words in defuns:: Executing the final code.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
835 * lambda:: How to write an anonymous function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
836 * mapcar:: Apply a function to elements of a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
837 * Another Bug:: Yet another bug @dots{} most insidious.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
838 * Final printed graph:: The graph itself!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
839
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
840 @end detailmenu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
841 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
842
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
843 @node Preface, List Processing, Top, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
844 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
845 @unnumbered Preface
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
846
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
847 Most of the GNU Emacs integrated environment is written in the programming
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
848 language called Emacs Lisp. The code written in this programming
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
849 language is the software---the sets of instructions---that tell the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
850 computer what to do when you give it commands. Emacs is designed so
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
851 that you can write new code in Emacs Lisp and easily install it as an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
852 extension to the editor.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
853
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
854 (GNU Emacs is sometimes called an ``extensible editor'', but it does
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
855 much more than provide editing capabilities. It is better to refer to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
856 Emacs as an ``extensible computing environment''. However, that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
857 phrase is quite a mouthful. It is easier to refer to Emacs simply as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
858 an editor. Moreover, everything you do in Emacs---find the Mayan date
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
859 and phases of the moon, simplify polynomials, debug code, manage
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
860 files, read letters, write books---all these activities are kinds of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
861 editing in the most general sense of the word.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
862
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
863 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
864 * Why:: Why learn Emacs Lisp?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
865 * On Reading this Text:: Read, gain familiarity, pick up habits....
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
866 * Who You Are:: For whom this is written.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
867 * Lisp History::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
868 * Note for Novices:: You can read this as a novice.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
869 * Thank You::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
870 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
871
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
872 @node Why, On Reading this Text, Preface, Preface
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
873 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
874 @unnumberedsec Why Study Emacs Lisp?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
875 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
876
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
877 Although Emacs Lisp is usually thought of in association only with Emacs,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
878 it is a full computer programming language. You can use Emacs Lisp as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
879 you would any other programming language.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
880
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
881 Perhaps you want to understand programming; perhaps you want to extend
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
882 Emacs; or perhaps you want to become a programmer. This introduction to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
883 Emacs Lisp is designed to get you started: to guide you in learning the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
884 fundamentals of programming, and more importantly, to show you how you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
885 can teach yourself to go further.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
886
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
887 @node On Reading this Text, Who You Are, Why, Preface
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
888 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
889 @unnumberedsec On Reading this Text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
890
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
891 All through this document, you will see little sample programs you can
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
892 run inside of Emacs. If you read this document in Info inside of GNU
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
893 Emacs, you can run the programs as they appear. (This is easy to do and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
894 is explained when the examples are presented.) Alternatively, you can
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
895 read this introduction as a printed book while sitting beside a computer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
896 running Emacs. (This is what I like to do; I like printed books.) If
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
897 you don't have a running Emacs beside you, you can still read this book,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
898 but in this case, it is best to treat it as a novel or as a travel guide
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
899 to a country not yet visited: interesting, but not the same as being
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
900 there.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
901
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
902 Much of this introduction is dedicated to walk-throughs or guided tours
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
903 of code used in GNU Emacs. These tours are designed for two purposes:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
904 first, to give you familiarity with real, working code (code you use
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
905 every day); and, second, to give you familiarity with the way Emacs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
906 works. It is interesting to see how a working environment is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
907 implemented.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
908 Also, I
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
909 hope that you will pick up the habit of browsing through source code.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
910 You can learn from it and mine it for ideas. Having GNU Emacs is like
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
911 having a dragon's cave of treasures.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
912
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
913 In addition to learning about Emacs as an editor and Emacs Lisp as a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
914 programming language, the examples and guided tours will give you an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
915 opportunity to get acquainted with Emacs as a Lisp programming
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
916 environment. GNU Emacs supports programming and provides tools that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
917 you will want to become comfortable using, such as @kbd{M-.} (the key
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
918 which invokes the @code{find-tag} command). You will also learn about
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
919 buffers and other objects that are part of the environment.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
920 Learning about these features of Emacs is like learning new routes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
921 around your home town.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
922
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
923 @ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
924 In addition, I have written several programs as extended examples.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
925 Although these are examples, the programs are real. I use them.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
926 Other people use them. You may use them. Beyond the fragments of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
927 programs used for illustrations, there is very little in here that is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
928 `just for teaching purposes'; what you see is used. This is a great
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
929 advantage of Emacs Lisp: it is easy to learn to use it for work.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
930 @end ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
931
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
932 Finally, I hope to convey some of the skills for using Emacs to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
933 learn aspects of programming that you don't know. You can often use
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
934 Emacs to help you understand what puzzles you or to find out how to do
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
935 something new. This self-reliance is not only a pleasure, but an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
936 advantage.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
937
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
938 @node Who You Are, Lisp History, On Reading this Text, Preface
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
939 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
940 @unnumberedsec For Whom This is Written
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
941
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
942 This text is written as an elementary introduction for people who are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
943 not programmers. If you are a programmer, you may not be satisfied with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
944 this primer. The reason is that you may have become expert at reading
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
945 reference manuals and be put off by the way this text is organized.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
946
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
947 An expert programmer who reviewed this text said to me:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
948
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
949 @quotation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
950 @i{I prefer to learn from reference manuals. I ``dive into'' each
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
951 paragraph, and ``come up for air'' between paragraphs.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
952
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
953 @i{When I get to the end of a paragraph, I assume that that subject is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
954 done, finished, that I know everything I need (with the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
955 possible exception of the case when the next paragraph starts talking
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
956 about it in more detail). I expect that a well written reference manual
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
957 will not have a lot of redundancy, and that it will have excellent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
958 pointers to the (one) place where the information I want is.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
959 @end quotation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
960
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
961 This introduction is not written for this person!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
962
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
963 Firstly, I try to say everything at least three times: first, to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
964 introduce it; second, to show it in context; and third, to show it in a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
965 different context, or to review it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
966
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
967 Secondly, I hardly ever put all the information about a subject in one
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
968 place, much less in one paragraph. To my way of thinking, that imposes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
969 too heavy a burden on the reader. Instead I try to explain only what
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
970 you need to know at the time. (Sometimes I include a little extra
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
971 information so you won't be surprised later when the additional
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
972 information is formally introduced.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
973
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
974 When you read this text, you are not expected to learn everything the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
975 first time. Frequently, you need only make, as it were, a `nodding
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
976 acquaintance' with some of the items mentioned. My hope is that I have
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
977 structured the text and given you enough hints that you will be alert to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
978 what is important, and concentrate on it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
979
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
980 You will need to ``dive into'' some paragraphs; there is no other way
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
981 to read them. But I have tried to keep down the number of such
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
982 paragraphs. This book is intended as an approachable hill, rather than
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
983 as a daunting mountain.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
984
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
985 This introduction to @cite{Programming in Emacs Lisp} has a companion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
986 document,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
987 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
988 @cite{The GNU Emacs Lisp Reference Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
989 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
990 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
991 @ref{Top, , The GNU Emacs Lisp Reference Manual, elisp, The GNU
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
992 Emacs Lisp Reference Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
993 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
994 The reference manual has more detail than this introduction. In the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
995 reference manual, all the information about one topic is concentrated
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
996 in one place. You should turn to it if you are like the programmer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
997 quoted above. And, of course, after you have read this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
998 @cite{Introduction}, you will find the @cite{Reference Manual} useful
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
999 when you are writing your own programs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1001 @node Lisp History, Note for Novices, Who You Are, Preface
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1002 @unnumberedsec Lisp History
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1003 @cindex Lisp history
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1004
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1005 Lisp was first developed in the late 1950s at the Massachusetts
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1006 Institute of Technology for research in artificial intelligence. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1007 great power of the Lisp language makes it superior for other purposes as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1008 well, such as writing editor commands and integrated environments.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1009
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1010 @cindex Maclisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1011 @cindex Common Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1012 GNU Emacs Lisp is largely inspired by Maclisp, which was written at MIT
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1013 in the 1960s. It is somewhat inspired by Common Lisp, which became a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1014 standard in the 1980s. However, Emacs Lisp is much simpler than Common
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1015 Lisp. (The standard Emacs distribution contains an optional extensions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1016 file, @file{cl.el}, that adds many Common Lisp features to Emacs Lisp.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1017
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1018 @node Note for Novices, Thank You, Lisp History, Preface
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1019 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1020 @unnumberedsec A Note for Novices
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1021
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1022 If you don't know GNU Emacs, you can still read this document
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1023 profitably. However, I recommend you learn Emacs, if only to learn to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1024 move around your computer screen. You can teach yourself how to use
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1025 Emacs with the on-line tutorial. To use it, type @kbd{C-h t}. (This
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1026 means you press and release the @key{CTRL} key and the @kbd{h} at the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1027 same time, and then press and release @kbd{t}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1028
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1029 Also, I often refer to one of Emacs' standard commands by listing the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1030 keys which you press to invoke the command and then giving the name of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1031 the command in parentheses, like this: @kbd{M-C-\}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1032 (@code{indent-region}). What this means is that the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1033 @code{indent-region} command is customarily invoked by typing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1034 @kbd{M-C-\}. (You can, if you wish, change the keys that are typed to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1035 invoke the command; this is called @dfn{rebinding}. @xref{Keymaps, ,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1036 Keymaps}.) The abbreviation @kbd{M-C-\} means that you type your
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1037 @key{META} key, @key{CTRL} key and @key{\} key all at the same time.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1038 (On many modern keyboards the @key{META} key is labelled
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1039 @key{ALT}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1040 Sometimes a combination like this is called a keychord, since it is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1041 similar to the way you play a chord on a piano. If your keyboard does
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1042 not have a @key{META} key, the @key{ESC} key prefix is used in place
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1043 of it. In this case, @kbd{M-C-\} means that you press and release your
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1044 @key{ESC} key and then type the @key{CTRL} key and the @key{\} key at
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1045 the same time. But usually @kbd{M-C-\} means press the @key{CTRL} key
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1046 along with the key that is labelled @key{ALT} and, at the same time,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1047 press the @key{\} key.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1048
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1049 In addition to typing a lone keychord, you can prefix what you type
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1050 with @kbd{C-u}, which is called the `universal argument'. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1051 @kbd{C-u} keychord passes an argument to the subsequent command.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1052 Thus, to indent a region of plain text by 6 spaces, mark the region,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1053 and then type @w{@kbd{C-u 6 M-C-\}}. (If you do not specify a number,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1054 Emacs either passes the number 4 to the command or otherwise runs the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1055 command differently than it would otherwise.) @xref{Arguments, ,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1056 Numeric Arguments, emacs, The GNU Emacs Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1057
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1058 If you are reading this in Info using GNU Emacs, you can read through
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1059 this whole document just by pressing the space bar, @key{SPC}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1060 (To learn about Info, type @kbd{C-h i} and then select Info.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1061
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1062 A note on terminology: when I use the word Lisp alone, I often am
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1063 referring to the various dialects of Lisp in general, but when I speak
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1064 of Emacs Lisp, I am referring to GNU Emacs Lisp in particular.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1065
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1066 @node Thank You, , Note for Novices, Preface
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1067 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1068 @unnumberedsec Thank You
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1069
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1070 My thanks to all who helped me with this book. My especial thanks to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1071 @r{Jim Blandy}, @r{Noah Friedman}, @w{Jim Kingdon}, @r{Roland
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1072 McGrath}, @w{Frank Ritter}, @w{Randy Smith}, @w{Richard M.@:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1073 Stallman}, and @w{Melissa Weisshaus}. My thanks also go to both
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1074 @w{Philip Johnson} and @w{David Stampe} for their patient
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1075 encouragement. My mistakes are my own.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1076
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1077 @flushright
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1078 Robert J. Chassell
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1079 @end flushright
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1080
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1081 @c ================ Beginning of main text ================
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1082
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1083 @c Start main text on right-hand (verso) page
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1084
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1085 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1086 \par\vfill\supereject
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1087 \headings off
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1088 \ifodd\pageno
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1089 \par\vfill\supereject
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1090 \else
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1091 \par\vfill\supereject
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1092 \page\hbox{}\page
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1093 \par\vfill\supereject
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1094 \fi
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1095 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1096
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1097 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1098 @headings off
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1099 @evenheading @thispage @| @| @thischapter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1100 @oddheading @thissection @| @| @thispage
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1101 @pageno = 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1102 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1103
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1104 @node List Processing, Practicing Evaluation, Preface, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1105 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1106 @chapter List Processing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1107
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1108 To the untutored eye, Lisp is a strange programming language. In Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1109 code there are parentheses everywhere. Some people even claim that the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1110 name stands for `Lots of Isolated Silly Parentheses'. But the claim is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1111 unwarranted. Lisp stands for LISt Processing, and the programming
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1112 language handles @emph{lists} (and lists of lists) by putting them
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1113 between parentheses. The parentheses mark the boundaries of the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1114 Sometimes a list is preceded by a single apostrophe or quotation mark,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1115 @samp{'}. Lists are the basis of Lisp.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1116
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1117 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1118 * Lisp Lists:: What are lists?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1119 * Run a Program:: Any list in Lisp is a program ready to run.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1120 * Making Errors:: Generating an error message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1121 * Names & Definitions:: Names of symbols and function definitions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1122 * Lisp Interpreter:: What the Lisp interpreter does.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1123 * Evaluation:: Running a program.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1124 * Variables:: Returning a value from a variable.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1125 * Arguments:: Passing information to a function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1126 * set & setq:: Setting the value of a variable.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1127 * Summary:: The major points.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1128 * Error Message Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1129 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1130
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1131 @node Lisp Lists, Run a Program, List Processing, List Processing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1132 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1133 @section Lisp Lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1134 @cindex Lisp Lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1135
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1136 In Lisp, a list looks like this: @code{'(rose violet daisy buttercup)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1137 This list is preceded by a single apostrophe. It could just as well be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1138 written as follows, which looks more like the kind of list you are likely
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1139 to be familiar with:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1140
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1141 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1142 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1143 '(rose
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1144 violet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1145 daisy
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1146 buttercup)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1147 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1148 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1149
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1150 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1151 The elements of this list are the names of the four different flowers,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1152 separated from each other by whitespace and surrounded by parentheses,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1153 like flowers in a field with a stone wall around them.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1154 @cindex Flowers in a field
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1155
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1156 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1157 * Numbers Lists:: List have numbers, other lists, in them.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1158 * Lisp Atoms:: Elemental entities.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1159 * Whitespace in Lists:: Formating lists to be readable.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1160 * Typing Lists:: How GNU Emacs helps you type lists.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1161 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1162
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1163 @node Numbers Lists, Lisp Atoms, Lisp Lists, Lisp Lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1164 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1165 @unnumberedsubsec Numbers, Lists inside of Lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1166 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1167
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1168 Lists can also have numbers in them, as in this list: @code{(+ 2 2)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1169 This list has a plus-sign, @samp{+}, followed by two @samp{2}s, each
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1170 separated by whitespace.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1171
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1172 In Lisp, both data and programs are represented the same way; that is,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1173 they are both lists of words, numbers, or other lists, separated by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1174 whitespace and surrounded by parentheses. (Since a program looks like
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1175 data, one program may easily serve as data for another; this is a very
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1176 powerful feature of Lisp.) (Incidentally, these two parenthetical
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1177 remarks are @emph{not} Lisp lists, because they contain @samp{;} and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1178 @samp{.} as punctuation marks.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1179
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1180 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1181 Here is another list, this time with a list inside of it:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1182
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1183 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1184 '(this list has (a list inside of it))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1185 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1186
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1187 The components of this list are the words @samp{this}, @samp{list},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1188 @samp{has}, and the list @samp{(a list inside of it)}. The interior
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1189 list is made up of the words @samp{a}, @samp{list}, @samp{inside},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1190 @samp{of}, @samp{it}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1191
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1192 @node Lisp Atoms, Whitespace in Lists, Numbers Lists, Lisp Lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1193 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1194 @subsection Lisp Atoms
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1195 @cindex Lisp Atoms
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1196
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1197 In Lisp, what we have been calling words are called @dfn{atoms}. This
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1198 term comes from the historical meaning of the word atom, which means
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1199 `indivisible'. As far as Lisp is concerned, the words we have been
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1200 using in the lists cannot be divided into any smaller parts and still
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1201 mean the same thing as part of a program; likewise with numbers and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1202 single character symbols like @samp{+}. On the other hand, unlike an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1203 atom, a list can be split into parts. (@xref{car cdr & cons, ,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1204 @code{car} @code{cdr} & @code{cons} Fundamental Functions}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1205
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1206 In a list, atoms are separated from each other by whitespace. They can be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1207 right next to a parenthesis.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1208
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1209 @cindex @samp{empty list} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1210 Technically speaking, a list in Lisp consists of parentheses surrounding
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1211 atoms separated by whitespace or surrounding other lists or surrounding
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1212 both atoms and other lists. A list can have just one atom in it or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1213 have nothing in it at all. A list with nothing in it looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1214 @code{()}, and is called the @dfn{empty list}. Unlike anything else, an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1215 empty list is considered both an atom and a list at the same time.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1216
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1217 @cindex Symbolic expressions, introduced
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1218 @cindex @samp{expression} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1219 @cindex @samp{form} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1220 The printed representation of both atoms and lists are called
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1221 @dfn{symbolic expressions} or, more concisely, @dfn{s-expressions}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1222 The word @dfn{expression} by itself can refer to either the printed
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1223 representation, or to the atom or list as it is held internally in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1224 computer. Often, people use the term @dfn{expression}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1225 indiscriminately. (Also, in many texts, the word @dfn{form} is used
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1226 as a synonym for expression.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1227
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1228 Incidentally, the atoms that make up our universe were named such when
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1229 they were thought to be indivisible; but it has been found that physical
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1230 atoms are not indivisible. Parts can split off an atom or it can
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1231 fission into two parts of roughly equal size. Physical atoms were named
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1232 prematurely, before their truer nature was found. In Lisp, certain
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1233 kinds of atom, such as an array, can be separated into parts; but the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1234 mechanism for doing this is different from the mechanism for splitting a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1235 list. As far as list operations are concerned, the atoms of a list are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1236 unsplittable.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1237
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1238 As in English, the meanings of the component letters of a Lisp atom
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1239 are different from the meaning the letters make as a word. For
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1240 example, the word for the South American sloth, the @samp{ai}, is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1241 completely different from the two words, @samp{a}, and @samp{i}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1242
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1243 There are many kinds of atom in nature but only a few in Lisp: for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1244 example, @dfn{numbers}, such as 37, 511, or 1729, and @dfn{symbols}, such
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1245 as @samp{+}, @samp{foo}, or @samp{forward-line}. The words we have
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1246 listed in the examples above are all symbols. In everyday Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1247 conversation, the word ``atom'' is not often used, because programmers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1248 usually try to be more specific about what kind of atom they are dealing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1249 with. Lisp programming is mostly about symbols (and sometimes numbers)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1250 within lists. (Incidentally, the preceding three word parenthetical
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1251 remark is a proper list in Lisp, since it consists of atoms, which in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1252 this case are symbols, separated by whitespace and enclosed by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1253 parentheses, without any non-Lisp punctuation.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1254
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1255 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1256 In addition, text between double quotation marks---even sentences or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1257 paragraphs---is an atom. Here is an example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1258 @cindex Text between double quotation marks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1259
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1260 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1261 '(this list includes "text between quotation marks.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1262 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1263
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1264 @cindex @samp{string} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1265 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1266 In Lisp, all of the quoted text including the punctuation mark and the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1267 blank spaces is a single atom. This kind of atom is called a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1268 @dfn{string} (for `string of characters') and is the sort of thing that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1269 is used for messages that a computer can print for a human to read.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1270 Strings are a different kind of atom than numbers or symbols and are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1271 used differently.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1272
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1273 @node Whitespace in Lists, Typing Lists, Lisp Atoms, Lisp Lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1274 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1275 @subsection Whitespace in Lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1276 @cindex Whitespace in lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1277
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1278 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1279 The amount of whitespace in a list does not matter. From the point of view
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1280 of the Lisp language,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1281
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1282 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1283 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1284 '(this list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1285 looks like this)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1286 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1287 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1288
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1289 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1290 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1291 is exactly the same as this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1292
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1293 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1294 '(this list looks like this)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1295 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1296
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1297 Both examples show what to Lisp is the same list, the list made up of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1298 the symbols @samp{this}, @samp{list}, @samp{looks}, @samp{like}, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1299 @samp{this} in that order.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1300
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1301 Extra whitespace and newlines are designed to make a list more readable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1302 by humans. When Lisp reads the expression, it gets rid of all the extra
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1303 whitespace (but it needs to have at least one space between atoms in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1304 order to tell them apart.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1305
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1306 Odd as it seems, the examples we have seen cover almost all of what Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1307 lists look like! Every other list in Lisp looks more or less like one
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1308 of these examples, except that the list may be longer and more complex.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1309 In brief, a list is between parentheses, a string is between quotation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1310 marks, a symbol looks like a word, and a number looks like a number.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1311 (For certain situations, square brackets, dots and a few other special
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1312 characters may be used; however, we will go quite far without them.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1313
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1314 @node Typing Lists, , Whitespace in Lists, Lisp Lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1315 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1316 @subsection GNU Emacs Helps You Type Lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1317 @cindex Help typing lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1318 @cindex Formatting help
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1319
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1320 When you type a Lisp expression in GNU Emacs using either Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1321 Interaction mode or Emacs Lisp mode, you have available to you several
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1322 commands to format the Lisp expression so it is easy to read. For
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1323 example, pressing the @key{TAB} key automatically indents the line the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1324 cursor is on by the right amount. A command to properly indent the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1325 code in a region is customarily bound to @kbd{M-C-\}. Indentation is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1326 designed so that you can see which elements of a list belongs to which
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1327 list---elements of a sub-list are indented more than the elements of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1328 the enclosing list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1329
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1330 In addition, when you type a closing parenthesis, Emacs momentarily
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1331 jumps the cursor back to the matching opening parenthesis, so you can
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1332 see which one it is. This is very useful, since every list you type
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1333 in Lisp must have its closing parenthesis match its opening
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1334 parenthesis. (@xref{Major Modes, , Major Modes, emacs, The GNU Emacs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1335 Manual}, for more information about Emacs' modes.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1336
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1337 @node Run a Program, Making Errors, Lisp Lists, List Processing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1338 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1339 @section Run a Program
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1340 @cindex Run a program
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1341 @cindex Program, running one
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1342
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1343 @cindex @samp{evaluate} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1344 A list in Lisp---any list---is a program ready to run. If you run it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1345 (for which the Lisp jargon is @dfn{evaluate}), the computer will do one
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1346 of three things: do nothing except return to you the list itself; send
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1347 you an error message; or, treat the first symbol in the list as a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1348 command to do something. (Usually, of course, it is the last of these
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1349 three things that you really want!)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1350
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1351 @c use code for the single apostrophe, not samp.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1352 The single apostrophe, @code{'}, that I put in front of some of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1353 example lists in preceding sections is called a @dfn{quote}; when it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1354 precedes a list, it tells Lisp to do nothing with the list, other than
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1355 take it as it is written. But if there is no quote preceding a list,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1356 the first item of the list is special: it is a command for the computer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1357 to obey. (In Lisp, these commands are called @emph{functions}.) The list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1358 @code{(+ 2 2)} shown above did not have a quote in front of it, so Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1359 understands that the @code{+} is an instruction to do something with the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1360 rest of the list: add the numbers that follow.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1361
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1362 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1363 If you are reading this inside of GNU Emacs in Info, here is how you can
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1364 evaluate such a list: place your cursor immediately after the right
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1365 hand parenthesis of the following list and then type @kbd{C-x C-e}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1366
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1367 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1368 (+ 2 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1369 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1370
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1371 @c use code for the number four, not samp.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1372 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1373 You will see the number @code{4} appear in the echo area. (In the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1374 jargon, what you have just done is ``evaluate the list.'' The echo area
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1375 is the line at the bottom of the screen that displays or ``echoes''
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1376 text.) Now try the same thing with a quoted list: place the cursor
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1377 right after the following list and type @kbd{C-x C-e}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1378
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1379 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1380 '(this is a quoted list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1381 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1382
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1383 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1384 You will see @code{(this is a quoted list)} appear in the echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1385
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1386 @cindex Lisp interpreter, explained
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1387 @cindex Interpreter, Lisp, explained
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1388 In both cases, what you are doing is giving a command to the program
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1389 inside of GNU Emacs called the @dfn{Lisp interpreter}---giving the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1390 interpreter a command to evaluate the expression. The name of the Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1391 interpreter comes from the word for the task done by a human who comes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1392 up with the meaning of an expression---who ``interprets'' it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1393
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1394 You can also evaluate an atom that is not part of a list---one that is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1395 not surrounded by parentheses; again, the Lisp interpreter translates
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1396 from the humanly readable expression to the language of the computer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1397 But before discussing this (@pxref{Variables}), we will discuss what the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1398 Lisp interpreter does when you make an error.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1399
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1400 @node Making Errors, Names & Definitions, Run a Program, List Processing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1401 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1402 @section Generate an Error Message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1403 @cindex Generate an error message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1404 @cindex Error message generation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1405
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1406 Partly so you won't worry if you do it accidentally, we will now give
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1407 a command to the Lisp interpreter that generates an error message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1408 This is a harmless activity; and indeed, we will often try to generate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1409 error messages intentionally. Once you understand the jargon, error
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1410 messages can be informative. Instead of being called ``error''
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1411 messages, they should be called ``help'' messages. They are like
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1412 signposts to a traveller in a strange country; deciphering them can be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1413 hard, but once understood, they can point the way.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1414
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1415 The error message is generated by a built-in GNU Emacs debugger. We
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1416 will `enter the debugger'. You get out of the debugger by typing @code{q}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1417
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1418 What we will do is evaluate a list that is not quoted and does not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1419 have a meaningful command as its first element. Here is a list almost
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1420 exactly the same as the one we just used, but without the single-quote
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1421 in front of it. Position the cursor right after it and type @kbd{C-x
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1422 C-e}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1423
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1424 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1425 (this is an unquoted list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1426 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1427
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1428 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1429 What you see depends on which version of Emacs you are running. GNU
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1430 Emacs version 21 provides more information than version 20 and before.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1431 First, the more recent result of generating an error; then the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1432 earlier, version 20 result.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1433
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1434 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1435 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1436 In GNU Emacs version 21, a @file{*Backtrace*} window will open up and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1437 you will see the following in it:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1438
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1439 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1440 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1441 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1442 Debugger entered--Lisp error: (void-function this)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1443 (this is an unquoted list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1444 eval((this is an unquoted list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1445 eval-last-sexp-1(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1446 eval-last-sexp(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1447 call-interactively(eval-last-sexp)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1448 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1449 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1450 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1451
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1452 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1453 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1454 Your cursor will be in this window (you may have to wait a few seconds
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1455 before it becomes visible). To quit the debugger and make the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1456 debugger window go away, type:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1457
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1458 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1459 q
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1460 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1461
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1462 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1463 Please type @kbd{q} right now, so you become confident that you can
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1464 get out of the debugger. Then, type @kbd{C-x C-e} again to re-enter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1465 it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1466
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1467 @cindex @samp{function} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1468 Based on what we already know, we can almost read this error message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1469
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1470 You read the @file{*Backtrace*} buffer from the bottom up; it tells
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1471 you what Emacs did. When you typed @kbd{C-x C-e}, you made an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1472 interactive call to the command @code{eval-last-sexp}. @code{eval} is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1473 an abbreviation for `evaluate' and @code{sexp} is an abbreviation for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1474 `symbolic expression'. The command means `evaluate last symbolic
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1475 expression', which is the expression just before your cursor.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1476
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1477 Each line above tells you what the Lisp interpreter evaluated next.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1478 The most recent action is at the top. The buffer is called the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1479 @file{*Backtrace*} buffer because it enables you to track Emacs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1480 backwards.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1481
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1482 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1483 At the top of the @file{*Backtrace*} buffer, you see the line:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1484
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1485 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1486 Debugger entered--Lisp error: (void-function this)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1487 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1488
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1489 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1490 The Lisp interpreter tried to evaluate the first atom of the list, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1491 word @samp{this}. It is this action that generated the error message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1492 @samp{void-function this}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1493
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1494 The message contains the words @samp{void-function} and @samp{this}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1495
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1496 @cindex @samp{function} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1497 The word @samp{function} was mentioned once before. It is a very
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1498 important word. For our purposes, we can define it by saying that a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1499 @dfn{function} is a set of instructions to the computer that tell the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1500 computer to do something.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1501
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1502 Now we can begin to understand the error message: @samp{void-function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1503 this}. The function (that is, the word @samp{this}) does not have a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1504 definition of any set of instructions for the computer to carry out.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1505
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1506 The slightly odd word, @samp{void-function}, is designed to cover the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1507 way Emacs Lisp is implemented, which is that when a symbol does not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1508 have a function definition attached to it, the place that should
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1509 contain the instructions is `void'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1510
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1511 On the other hand, since we were able to add 2 plus 2 successfully, by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1512 evaluating @code{(+ 2 2)}, we can infer that the symbol @code{+} must
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1513 have a set of instructions for the computer to obey and those
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1514 instructions must be to add the numbers that follow the @code{+}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1515
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1516 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1517 In GNU Emacs version 20, and in earlier versions, you will see only
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1518 one line of error message; it will appear in the echo area and look
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1519 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1520
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1521 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1522 Symbol's function definition is void:@: this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1523 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1524
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1525 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1526 (Also, your terminal may beep at you---some do, some don't; and others
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1527 blink. This is just a device to get your attention.) The message goes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1528 away as soon as you type another key, even just to move the cursor.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1529
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1530 We know the meaning of the word @samp{Symbol}. It refers to the first
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1531 atom of the list, the word @samp{this}. The word @samp{function}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1532 refers to the instructions that tell the computer what to do.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1533 (Technically, the symbol tells the computer where to find the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1534 instructions, but this is a complication we can ignore for the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1535 moment.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1536
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1537 The error message can be understood: @samp{Symbol's function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1538 definition is void:@: this}. The symbol (that is, the word
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1539 @samp{this}) lacks instructions for the computer to carry out.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1540
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1541 @node Names & Definitions, Lisp Interpreter, Making Errors, List Processing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1542 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1543 @section Symbol Names and Function Definitions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1544 @cindex Symbol names
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1545
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1546 We can articulate another characteristic of Lisp based on what we have
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1547 discussed so far---an important characteristic: a symbol, like
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1548 @code{+}, is not itself the set of instructions for the computer to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1549 carry out. Instead, the symbol is used, perhaps temporarily, as a way
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1550 of locating the definition or set of instructions. What we see is the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1551 name through which the instructions can be found. Names of people
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1552 work the same way. I can be referred to as @samp{Bob}; however, I am
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1553 not the letters @samp{B}, @samp{o}, @samp{b} but am the consciousness
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1554 consistently associated with a particular life-form. The name is not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1555 me, but it can be used to refer to me.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1556
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1557 In Lisp, one set of instructions can be attached to several names.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1558 For example, the computer instructions for adding numbers can be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1559 linked to the symbol @code{plus} as well as to the symbol @code{+}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1560 (and are in some dialects of Lisp). Among humans, I can be referred
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1561 to as @samp{Robert} as well as @samp{Bob} and by other words as well.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1562
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1563 On the other hand, a symbol can have only one function definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1564 attached to it at a time. Otherwise, the computer would be confused as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1565 to which definition to use. If this were the case among people, only
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1566 one person in the world could be named @samp{Bob}. However, the function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1567 definition to which the name refers can be changed readily.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1568 (@xref{Install, , Install a Function Definition}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1569
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1570 Since Emacs Lisp is large, it is customary to name symbols in a way
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1571 that identifies the part of Emacs to which the function belongs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1572 Thus, all the names for functions that deal with Texinfo start with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1573 @samp{texinfo-} and those for functions that deal with reading mail
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1574 start with @samp{rmail-}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1575
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1576 @node Lisp Interpreter, Evaluation, Names & Definitions, List Processing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1577 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1578 @section The Lisp Interpreter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1579 @cindex Lisp interpreter, what it does
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1580 @cindex Interpreter, what it does
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1581
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1582 Based on what we have seen, we can now start to figure out what the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1583 Lisp interpreter does when we command it to evaluate a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1584 First, it looks to see whether there is a quote before the list; if
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1585 there is, the interpreter just gives us the list. On the other
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1586 hand, if there is no quote, the interpreter looks at the first element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1587 in the list and sees whether it has a function definition. If it does,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1588 the interpreter carries out the instructions in the function definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1589 Otherwise, the interpreter prints an error message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1590
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1591 This is how Lisp works. Simple. There are added complications which we
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1592 will get to in a minute, but these are the fundamentals. Of course, to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1593 write Lisp programs, you need to know how to write function definitions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1594 and attach them to names, and how to do this without confusing either
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1595 yourself or the computer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1596
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1597 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1598 * Complications:: Variables, Special forms, Lists within.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1599 * Byte Compiling:: Specially processing code for speed.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1600 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1601
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1602 @node Complications, Byte Compiling, Lisp Interpreter, Lisp Interpreter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1603 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1604 @unnumberedsubsec Complications
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1605 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1606
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1607 Now, for the first complication. In addition to lists, the Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1608 interpreter can evaluate a symbol that is not quoted and does not have
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1609 parentheses around it. The Lisp interpreter will attempt to determine
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1610 the symbol's value as a @dfn{variable}. This situation is described
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1611 in the section on variables. (@xref{Variables}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1612
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1613 @cindex Special form
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1614 The second complication occurs because some functions are unusual and do
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1615 not work in the usual manner. Those that don't are called @dfn{special
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1616 forms}. They are used for special jobs, like defining a function, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1617 there are not many of them. In the next few chapters, you will be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1618 introduced to several of the more important special forms.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1619
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1620 The third and final complication is this: if the function that the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1621 Lisp interpreter is looking at is not a special form, and if it is part
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1622 of a list, the Lisp interpreter looks to see whether the list has a list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1623 inside of it. If there is an inner list, the Lisp interpreter first
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1624 figures out what it should do with the inside list, and then it works on
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1625 the outside list. If there is yet another list embedded inside the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1626 inner list, it works on that one first, and so on. It always works on
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1627 the innermost list first. The interpreter works on the innermost list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1628 first, to evaluate the result of that list. The result may be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1629 used by the enclosing expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1630
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1631 Otherwise, the interpreter works left to right, from one expression to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1632 the next.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1633
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1634 @node Byte Compiling, , Complications, Lisp Interpreter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1635 @subsection Byte Compiling
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1636 @cindex Byte compiling
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1637
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1638 One other aspect of interpreting: the Lisp interpreter is able to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1639 interpret two kinds of entity: humanly readable code, on which we will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1640 focus exclusively, and specially processed code, called @dfn{byte
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1641 compiled} code, which is not humanly readable. Byte compiled code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1642 runs faster than humanly readable code.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1643
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1644 You can transform humanly readable code into byte compiled code by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1645 running one of the compile commands such as @code{byte-compile-file}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1646 Byte compiled code is usually stored in a file that ends with a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1647 @file{.elc} extension rather than a @file{.el} extension. You will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1648 see both kinds of file in the @file{emacs/lisp} directory; the files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1649 to read are those with @file{.el} extensions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1650
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1651 As a practical matter, for most things you might do to customize or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1652 extend Emacs, you do not need to byte compile; and I will not discuss
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1653 the topic here. @xref{Byte Compilation, , Byte Compilation, elisp,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1654 The GNU Emacs Lisp Reference Manual}, for a full description of byte
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1655 compilation.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1656
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1657 @node Evaluation, Variables, Lisp Interpreter, List Processing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1658 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1659 @section Evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1660 @cindex Evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1661
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1662 When the Lisp interpreter works on an expression, the term for the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1663 activity is called @dfn{evaluation}. We say that the interpreter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1664 `evaluates the expression'. I've used this term several times before.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1665 The word comes from its use in everyday language, `to ascertain the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1666 value or amount of; to appraise', according to @cite{Webster's New
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1667 Collegiate Dictionary}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1668
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1669 After evaluating an expression, the Lisp interpreter will most likely
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1670 @dfn{return} the value that the computer produces by carrying out the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1671 instructions it found in the function definition, or perhaps it will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1672 give up on that function and produce an error message. (The interpreter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1673 may also find itself tossed, so to speak, to a different function or it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1674 may attempt to repeat continually what it is doing for ever and ever in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1675 what is called an `infinite loop'. These actions are less common; and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1676 we can ignore them.) Most frequently, the interpreter returns a value.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1677
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1678 @cindex @samp{side effect} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1679 At the same time the interpreter returns a value, it may do something
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1680 else as well, such as move a cursor or copy a file; this other kind of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1681 action is called a @dfn{side effect}. Actions that we humans think are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1682 important, such as printing results, are often ``side effects'' to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1683 Lisp interpreter. The jargon can sound peculiar, but it turns out that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1684 it is fairly easy to learn to use side effects.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1685
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1686 In summary, evaluating a symbolic expression most commonly causes the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1687 Lisp interpreter to return a value and perhaps carry out a side effect;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1688 or else produce an error.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1689
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1690 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1691 * Evaluating Inner Lists:: Lists within lists...
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1692 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1693
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1694 @node Evaluating Inner Lists, , Evaluation, Evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1695 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1696 @subsection Evaluating Inner Lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1697 @cindex Inner list evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1698 @cindex Evaluating inner lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1699
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1700 If evaluation applies to a list that is inside another list, the outer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1701 list may use the value returned by the first evaluation as information
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1702 when the outer list is evaluated. This explains why inner expressions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1703 are evaluated first: the values they return are used by the outer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1704 expressions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1705
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1706 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1707 We can investigate this process by evaluating another addition example.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1708 Place your cursor after the following expression and type @kbd{C-x C-e}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1709
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1710 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1711 (+ 2 (+ 3 3))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1712 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1713
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1714 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1715 The number 8 will appear in the echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1716
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1717 What happens is that the Lisp interpreter first evaluates the inner
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1718 expression, @code{(+ 3 3)}, for which the value 6 is returned; then it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1719 evaluates the outer expression as if it were written @code{(+ 2 6)}, which
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1720 returns the value 8. Since there are no more enclosing expressions to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1721 evaluate, the interpreter prints that value in the echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1722
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1723 Now it is easy to understand the name of the command invoked by the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1724 keystrokes @kbd{C-x C-e}: the name is @code{eval-last-sexp}. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1725 letters @code{sexp} are an abbreviation for `symbolic expression', and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1726 @code{eval} is an abbreviation for `evaluate'. The command means
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1727 `evaluate last symbolic expression'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1728
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1729 As an experiment, you can try evaluating the expression by putting the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1730 cursor at the beginning of the next line immediately following the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1731 expression, or inside the expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1732
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1733 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1734 Here is another copy of the expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1735
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1736 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1737 (+ 2 (+ 3 3))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1738 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1739
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1740 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1741 If you place the cursor at the beginning of the blank line that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1742 immediately follows the expression and type @kbd{C-x C-e}, you will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1743 still get the value 8 printed in the echo area. Now try putting the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1744 cursor inside the expression. If you put it right after the next to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1745 last parenthesis (so it appears to sit on top of the last parenthesis),
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1746 you will get a 6 printed in the echo area! This is because the command
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1747 evaluates the expression @code{(+ 3 3)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1748
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1749 Now put the cursor immediately after a number. Type @kbd{C-x C-e} and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1750 you will get the number itself. In Lisp, if you evaluate a number, you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1751 get the number itself---this is how numbers differ from symbols. If you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1752 evaluate a list starting with a symbol like @code{+}, you will get a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1753 value returned that is the result of the computer carrying out the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1754 instructions in the function definition attached to that name. If a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1755 symbol by itself is evaluated, something different happens, as we will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1756 see in the next section.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1757
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1758 @node Variables, Arguments, Evaluation, List Processing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1759 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1760 @section Variables
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1761 @cindex Variables
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1762
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1763 In Emacs Lisp, a symbol can have a value attached to it just as it can
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1764 have a function definition attached to it. The two are different.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1765 The function definition is a set of instructions that a computer will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1766 obey. A value, on the other hand, is something, such as number or a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1767 name, that can vary (which is why such a symbol is called a variable).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1768 The value of a symbol can be any expression in Lisp, such as a symbol,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1769 number, list, or string. A symbol that has a value is often called a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1770 @dfn{variable}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1771
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1772 A symbol can have both a function definition and a value attached to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1773 it at the same time. Or it can have just one or the other.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1774 The two are separate. This is somewhat similar
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1775 to the way the name Cambridge can refer to the city in Massachusetts
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1776 and have some information attached to the name as well, such as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1777 ``great programming center''.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1778
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1779 @ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1780 (Incidentally, in Emacs Lisp, a symbol can have two
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1781 other things attached to it, too: a property list and a documentation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1782 string; these are discussed later.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1783 @end ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1784
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1785 Another way to think about this is to imagine a symbol as being a chest
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1786 of drawers. The function definition is put in one drawer, the value in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1787 another, and so on. What is put in the drawer holding the value can be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1788 changed without affecting the contents of the drawer holding the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1789 function definition, and vice-versa.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1790
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1791 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1792 * fill-column Example::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1793 * Void Function:: The error message for a symbol
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1794 without a function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1795 * Void Variable:: The error message for a symbol without a value.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1796 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1797
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1798 @node fill-column Example, Void Function, Variables, Variables
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1799 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1800 @unnumberedsubsec @code{fill-column}, an Example Variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1801 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1802
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1803 @findex fill-column, @r{an example variable}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1804 @cindex Example variable, @code{fill-column}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1805 @cindex Variable, example of, @code{fill-column}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1806 The variable @code{fill-column} illustrates a symbol with a value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1807 attached to it: in every GNU Emacs buffer, this symbol is set to some
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1808 value, usually 72 or 70, but sometimes to some other value. To find the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1809 value of this symbol, evaluate it by itself. If you are reading this in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1810 Info inside of GNU Emacs, you can do this by putting the cursor after
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1811 the symbol and typing @kbd{C-x C-e}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1812
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1813 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1814 fill-column
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1815 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1816
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1817 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1818 After I typed @kbd{C-x C-e}, Emacs printed the number 72 in my echo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1819 area. This is the value for which @code{fill-column} is set for me as I
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1820 write this. It may be different for you in your Info buffer. Notice
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1821 that the value returned as a variable is printed in exactly the same way
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1822 as the value returned by a function carrying out its instructions. From
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1823 the point of view of the Lisp interpreter, a value returned is a value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1824 returned. What kind of expression it came from ceases to matter once
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1825 the value is known.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1826
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1827 A symbol can have any value attached to it or, to use the jargon, we can
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1828 @dfn{bind} the variable to a value: to a number, such as 72; to a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1829 string, @code{"such as this"}; to a list, such as @code{(spruce pine
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1830 oak)}; we can even bind a variable to a function definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1831
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1832 A symbol can be bound to a value in several ways. @xref{set & setq, ,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1833 Setting the Value of a Variable}, for information about one way to do
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1834 this.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1835
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1836 @node Void Function, Void Variable, fill-column Example, Variables
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1837 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1838 @subsection Error Message for a Symbol Without a Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1839 @cindex Symbol without function error
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1840 @cindex Error for symbol without function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1841
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1842 When we evaluated @code{fill-column} to find its value as a variable,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1843 we did not place parentheses around the word. This is because we did
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1844 not intend to use it as a function name.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1845
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1846 If @code{fill-column} were the first or only element of a list, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1847 Lisp interpreter would attempt to find the function definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1848 attached to it. But @code{fill-column} has no function definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1849 Try evaluating this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1850
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1851 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1852 (fill-column)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1853 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1854
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1855 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1856 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1857 In GNU Emacs version 21, you will create a @file{*Backtrace*} buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1858 that says:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1859
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1860 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1861 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1862 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1863 Debugger entered--Lisp error: (void-function fill-column)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1864 (fill-column)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1865 eval((fill-column))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1866 eval-last-sexp-1(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1867 eval-last-sexp(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1868 call-interactively(eval-last-sexp)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1869 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1870 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1871 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1872
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1873 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1874 (Remember, to quit the debugger and make the debugger window go away,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1875 type @kbd{q} in the @file{*Backtrace*} buffer.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1876
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1877 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1878 In GNU Emacs 20 and before, you will produce an error message that says:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1879
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1880 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1881 Symbol's function definition is void:@: fill-column
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1882 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1883
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1884 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1885 (The message will go away away as soon as you move the cursor or type
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1886 another key.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1887
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1888 @node Void Variable, , Void Function, Variables
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1889 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1890 @subsection Error Message for a Symbol Without a Value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1891 @cindex Symbol without value error
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1892 @cindex Error for symbol without value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1893
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1894 If you attempt to evaluate a symbol that does not have a value bound to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1895 it, you will receive an error message. You can see this by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1896 experimenting with our 2 plus 2 addition. In the following expression,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1897 put your cursor right after the @code{+}, before the first number 2,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1898 type @kbd{C-x C-e}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1899
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1900 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1901 (+ 2 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1902 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1903
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1904 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1905 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1906 In GNU Emacs 21, you will create a @file{*Backtrace*} buffer that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1907 says:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1908
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1909 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1910 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1911 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1912 Debugger entered--Lisp error: (void-variable +)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1913 eval(+)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1914 eval-last-sexp-1(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1915 eval-last-sexp(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1916 call-interactively(eval-last-sexp)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1917 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1918 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1919 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1920
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1921 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1922 (As with the other times we entered the debugger, you can quit by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1923 typing @kbd{q} in the @file{*Backtrace*} buffer.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1924
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1925 This backtrace is different from the very first error message we saw,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1926 which said, @samp{Debugger entered--Lisp error: (void-function this)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1927 In this case, the function does not have a value as a variable; while
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1928 in the other error message, the function (the word `this') did not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1929 have a definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1930
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1931 In this experiment with the @code{+}, what we did was cause the Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1932 interpreter to evaluate the @code{+} and look for the value of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1933 variable instead of the function definition. We did this by placing the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1934 cursor right after the symbol rather than after the parenthesis of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1935 enclosing list as we did before. As a consequence, the Lisp interpreter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1936 evaluated the preceding s-expression, which in this case was the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1937 @code{+} by itself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1938
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1939 Since @code{+} does not have a value bound to it, just the function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1940 definition, the error message reported that the symbol's value as a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1941 variable was void.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1942
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1943 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1944 In GNU Emacs version 20 and before, your error message will say:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1945
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1946 @example
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1947 Symbol's value as variable is void:@: +
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1948 @end example
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1949
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1950 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1951 The meaning is the same as in GNU Emacs 21.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1952
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1953 @node Arguments, set & setq, Variables, List Processing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1954 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1955 @section Arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1956 @cindex Arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1957 @cindex Passing information to functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1958
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1959 To see how information is passed to functions, let's look again at
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1960 our old standby, the addition of two plus two. In Lisp, this is written
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1961 as follows:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1962
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1963 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1964 (+ 2 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1965 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1966
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1967 If you evaluate this expression, the number 4 will appear in your echo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1968 area. What the Lisp interpreter does is add the numbers that follow
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1969 the @code{+}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1970
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1971 @cindex @samp{argument} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1972 The numbers added by @code{+} are called the @dfn{arguments} of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1973 function @code{+}. These numbers are the information that is given to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1974 or @dfn{passed} to the function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1975
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1976 The word `argument' comes from the way it is used in mathematics and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1977 does not refer to a disputation between two people; instead it refers to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1978 the information presented to the function, in this case, to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1979 @code{+}. In Lisp, the arguments to a function are the atoms or lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1980 that follow the function. The values returned by the evaluation of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1981 these atoms or lists are passed to the function. Different functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1982 require different numbers of arguments; some functions require none at
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1983 all.@footnote{It is curious to track the path by which the word `argument'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1984 came to have two different meanings, one in mathematics and the other in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1985 everyday English. According to the @cite{Oxford English Dictionary},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1986 the word derives from the Latin for @samp{to make clear, prove}; thus it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1987 came to mean, by one thread of derivation, `the evidence offered as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1988 proof', which is to say, `the information offered', which led to its
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1989 meaning in Lisp. But in the other thread of derivation, it came to mean
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1990 `to assert in a manner against which others may make counter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1991 assertions', which led to the meaning of the word as a disputation.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1992 (Note here that the English word has two different definitions attached
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1993 to it at the same time. By contrast, in Emacs Lisp, a symbol cannot
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1994 have two different function definitions at the same time.)}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1995
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1996 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1997 * Data types:: Types of data passed to a function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1998 * Args as Variable or List:: An argument can be the value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1999 of a variable or list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2000 * Variable Number of Arguments:: Some functions may take a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2001 variable number of arguments.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2002 * Wrong Type of Argument:: Passing an argument of the wrong type
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2003 to a function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2004 * message:: A useful function for sending messages.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2005 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2006
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2007 @node Data types, Args as Variable or List, Arguments, Arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2008 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2009 @subsection Arguments' Data Types
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2010 @cindex Data types
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2011 @cindex Types of data
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2012 @cindex Arguments' data types
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2013
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2014 The type of data that should be passed to a function depends on what
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2015 kind of information it uses. The arguments to a function such as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2016 @code{+} must have values that are numbers, since @code{+} adds numbers.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2017 Other functions use different kinds of data for their arguments.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2018
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2019 @findex concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2020 For example, the @code{concat} function links together or unites two or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2021 more strings of text to produce a string. The arguments are strings.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2022 Concatenating the two character strings @code{abc}, @code{def} produces
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2023 the single string @code{abcdef}. This can be seen by evaluating the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2024 following:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2025
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2026 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2027 (concat "abc" "def")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2028 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2029
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2030 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2031 The value produced by evaluating this expression is @code{"abcdef"}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2032
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2033 A function such as @code{substring} uses both a string and numbers as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2034 arguments. The function returns a part of the string, a substring of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2035 the first argument. This function takes three arguments. Its first
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2036 argument is the string of characters, the second and third arguments are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2037 numbers that indicate the beginning and end of the substring. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2038 numbers are a count of the number of characters (including spaces and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2039 punctuations) from the beginning of the string.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2040
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2041 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2042 For example, if you evaluate the following:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2043
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2044 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2045 (substring "The quick brown fox jumped." 16 19)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2046 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2047
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2048 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2049 you will see @code{"fox"} appear in the echo area. The arguments are the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2050 string and the two numbers.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2051
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2052 Note that the string passed to @code{substring} is a single atom even
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2053 though it is made up of several words separated by spaces. Lisp counts
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2054 everything between the two quotation marks as part of the string,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2055 including the spaces. You can think of the @code{substring} function as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2056 a kind of `atom smasher' since it takes an otherwise indivisible atom
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2057 and extracts a part. However, @code{substring} is only able to extract
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2058 a substring from an argument that is a string, not from another type of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2059 atom such as a number or symbol.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2060
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2061 @node Args as Variable or List, Variable Number of Arguments, Data types, Arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2062 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2063 @subsection An Argument as the Value of a Variable or List
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2064
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2065 An argument can be a symbol that returns a value when it is evaluated.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2066 For example, when the symbol @code{fill-column} by itself is evaluated,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2067 it returns a number. This number can be used in an addition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2068
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2069 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2070 Position the cursor after the following expression and type @kbd{C-x
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2071 C-e}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2072
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2073 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2074 (+ 2 fill-column)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2075 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2076
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2077 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2078 The value will be a number two more than what you get by evaluating
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2079 @code{fill-column} alone. For me, this is 74, because the value of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2080 @code{fill-column} is 72.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2081
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2082 As we have just seen, an argument can be a symbol that returns a value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2083 when evaluated. In addition, an argument can be a list that returns a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2084 value when it is evaluated. For example, in the following expression,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2085 the arguments to the function @code{concat} are the strings
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2086 @w{@code{"The "}} and @w{@code{" red foxes."}} and the list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2087 @code{(number-to-string (+ 2 fill-column))}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2088
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2089 @c For Emacs 21, need number-to-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2090 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2091 (concat "The " (number-to-string (+ 2 fill-column)) " red foxes.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2092 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2093
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2094 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2095 If you evaluate this expression---and if, as with my Emacs,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2096 @code{fill-column} evaluates to 72---@code{"The 74 red foxes."} will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2097 appear in the echo area. (Note that you must put spaces after the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2098 word @samp{The} and before the word @samp{red} so they will appear in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2099 the final string. The function @code{number-to-string} converts the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2100 integer that the addition function returns to a string.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2101 @code{number-to-string} is also known as @code{int-to-string}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2102
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2103 @node Variable Number of Arguments, Wrong Type of Argument, Args as Variable or List, Arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2104 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2105 @subsection Variable Number of Arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2106 @cindex Variable number of arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2107 @cindex Arguments, variable number of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2108
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2109 Some functions, such as @code{concat}, @code{+} or @code{*}, take any
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2110 number of arguments. (The @code{*} is the symbol for multiplication.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2111 This can be seen by evaluating each of the following expressions in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2112 the usual way. What you will see in the echo area is printed in this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2113 text after @samp{@result{}}, which you may read as `evaluates to'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2114
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2115 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2116 In the first set, the functions have no arguments:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2117
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2118 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2119 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2120 (+) @result{} 0
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2121
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2122 (*) @result{} 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2123 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2124 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2125
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2126 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2127 In this set, the functions have one argument each:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2128
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2129 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2130 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2131 (+ 3) @result{} 3
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2132
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2133 (* 3) @result{} 3
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2134 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2135 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2136
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2137 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2138 In this set, the functions have three arguments each:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2139
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2140 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2141 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2142 (+ 3 4 5) @result{} 12
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2143
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2144 (* 3 4 5) @result{} 60
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2145 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2146 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2147
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2148 @node Wrong Type of Argument, message, Variable Number of Arguments, Arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2149 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2150 @subsection Using the Wrong Type Object as an Argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2151 @cindex Wrong type of argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2152 @cindex Argument, wrong type of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2153
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2154 When a function is passed an argument of the wrong type, the Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2155 interpreter produces an error message. For example, the @code{+}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2156 function expects the values of its arguments to be numbers. As an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2157 experiment we can pass it the quoted symbol @code{hello} instead of a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2158 number. Position the cursor after the following expression and type
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2159 @kbd{C-x C-e}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2160
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2161 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2162 (+ 2 'hello)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2163 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2164
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2165 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2166 When you do this you will generate an error message. What has happened
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2167 is that @code{+} has tried to add the 2 to the value returned by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2168 @code{'hello}, but the value returned by @code{'hello} is the symbol
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2169 @code{hello}, not a number. Only numbers can be added. So @code{+}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2170 could not carry out its addition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2171
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2172 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2173 In GNU Emacs version 21, you will create and enter a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2174 @file{*Backtrace*} buffer that says:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2175
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2176 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2177 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2178 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2179 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2180 Debugger entered--Lisp error:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2181 (wrong-type-argument number-or-marker-p hello)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2182 +(2 hello)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2183 eval((+ 2 (quote hello)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2184 eval-last-sexp-1(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2185 eval-last-sexp(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2186 call-interactively(eval-last-sexp)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2187 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2188 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2189 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2190
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2191 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2192 As usual, the error message tries to be helpful and makes sense after you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2193 learn how to read it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2194
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2195 The first part of the error message is straightforward; it says
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2196 @samp{wrong type argument}. Next comes the mysterious jargon word
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2197 @w{@samp{number-or-marker-p}}. This word is trying to tell you what
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2198 kind of argument the @code{+} expected.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2199
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2200 The symbol @code{number-or-marker-p} says that the Lisp interpreter is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2201 trying to determine whether the information presented it (the value of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2202 the argument) is a number or a marker (a special object representing a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2203 buffer position). What it does is test to see whether the @code{+} is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2204 being given numbers to add. It also tests to see whether the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2205 argument is something called a marker, which is a specific feature of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2206 Emacs Lisp. (In Emacs, locations in a buffer are recorded as markers.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2207 When the mark is set with the @kbd{C-@@} or @kbd{C-@key{SPC}} command,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2208 its position is kept as a marker. The mark can be considered a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2209 number---the number of characters the location is from the beginning
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2210 of the buffer.) In Emacs Lisp, @code{+} can be used to add the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2211 numeric value of marker positions as numbers.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2212
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2213 The @samp{p} of @code{number-or-marker-p} is the embodiment of a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2214 practice started in the early days of Lisp programming. The @samp{p}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2215 stands for `predicate'. In the jargon used by the early Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2216 researchers, a predicate refers to a function to determine whether some
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2217 property is true or false. So the @samp{p} tells us that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2218 @code{number-or-marker-p} is the name of a function that determines
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2219 whether it is true or false that the argument supplied is a number or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2220 a marker. Other Lisp symbols that end in @samp{p} include @code{zerop},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2221 a function that tests whether its argument has the value of zero, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2222 @code{listp}, a function that tests whether its argument is a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2223
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2224 Finally, the last part of the error message is the symbol @code{hello}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2225 This is the value of the argument that was passed to @code{+}. If the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2226 addition had been passed the correct type of object, the value passed
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2227 would have been a number, such as 37, rather than a symbol like
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2228 @code{hello}. But then you would not have got the error message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2229
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2230 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2231 In GNU Emacs version 20 and before, the echo area displays an error
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2232 message that says:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2233
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2234 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2235 Wrong type argument:@: number-or-marker-p, hello
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2236 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2237
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2238 This says, in different words, the same as the top line of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2239 @file{*Backtrace*} buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2240
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2241 @node message, , Wrong Type of Argument, Arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2242 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2243 @subsection The @code{message} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2244 @findex message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2245
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2246 Like @code{+}, the @code{message} function takes a variable number of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2247 arguments. It is used to send messages to the user and is so useful
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2248 that we will describe it here.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2249
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2250 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2251 A message is printed in the echo area. For example, you can print a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2252 message in your echo area by evaluating the following list:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2253
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2254 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2255 (message "This message appears in the echo area!")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2256 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2257
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2258 The whole string between double quotation marks is a single argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2259 and is printed @i{in toto}. (Note that in this example, the message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2260 itself will appear in the echo area within double quotes; that is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2261 because you see the value returned by the @code{message} function. In
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2262 most uses of @code{message} in programs that you write, the text will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2263 be printed in the echo area as a side-effect, without the quotes.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2264 @xref{multiply-by-seven in detail, , @code{multiply-by-seven} in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2265 detail}, for an example of this.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2266
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2267 However, if there is a @samp{%s} in the quoted string of characters, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2268 @code{message} function does not print the @samp{%s} as such, but looks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2269 to the argument that follows the string. It evaluates the second
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2270 argument and prints the value at the location in the string where the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2271 @samp{%s} is.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2272
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2273 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2274 You can see this by positioning the cursor after the following
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2275 expression and typing @kbd{C-x C-e}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2276
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2277 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2278 (message "The name of this buffer is: %s." (buffer-name))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2279 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2280
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2281 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2282 In Info, @code{"The name of this buffer is: *info*."} will appear in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2283 echo area. The function @code{buffer-name} returns the name of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2284 buffer as a string, which the @code{message} function inserts in place
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2285 of @code{%s}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2286
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2287 To print a value as an integer, use @samp{%d} in the same way as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2288 @samp{%s}. For example, to print a message in the echo area that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2289 states the value of the @code{fill-column}, evaluate the following:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2290
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2291 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2292 (message "The value of fill-column is %d." fill-column)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2293 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2294
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2295 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2296 On my system, when I evaluate this list, @code{"The value of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2297 fill-column is 72."} appears in my echo area@footnote{Actually, you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2298 can use @code{%s} to print a number. It is non-specific. @code{%d}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2299 prints only the part of a number left of a decimal point, and not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2300 anything that is not a number.}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2301
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2302 If there is more than one @samp{%s} in the quoted string, the value of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2303 the first argument following the quoted string is printed at the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2304 location of the first @samp{%s} and the value of the second argument is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2305 printed at the location of the second @samp{%s}, and so on.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2306
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2307 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2308 For example, if you evaluate the following,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2309
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2310 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2311 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2312 (message "There are %d %s in the office!"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2313 (- fill-column 14) "pink elephants")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2314 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2315 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2316
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2317 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2318 a rather whimsical message will appear in your echo area. On my system
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2319 it says, @code{"There are 58 pink elephants in the office!"}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2320
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2321 The expression @code{(- fill-column 14)} is evaluated and the resulting
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2322 number is inserted in place of the @samp{%d}; and the string in double
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2323 quotes, @code{"pink elephants"}, is treated as a single argument and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2324 inserted in place of the @samp{%s}. (That is to say, a string between
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2325 double quotes evaluates to itself, like a number.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2326
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2327 Finally, here is a somewhat complex example that not only illustrates
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2328 the computation of a number, but also shows how you can use an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2329 expression within an expression to generate the text that is substituted
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2330 for @samp{%s}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2331
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2332 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2333 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2334 (message "He saw %d %s"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2335 (- fill-column 34)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2336 (concat "red "
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2337 (substring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2338 "The quick brown foxes jumped." 16 21)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2339 " leaping."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2340 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2341 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2342
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2343 In this example, @code{message} has three arguments: the string,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2344 @code{"He saw %d %s"}, the expression, @code{(- fill-column 32)}, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2345 the expression beginning with the function @code{concat}. The value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2346 resulting from the evaluation of @code{(- fill-column 32)} is inserted
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2347 in place of the @samp{%d}; and the value returned by the expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2348 beginning with @code{concat} is inserted in place of the @samp{%s}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2349
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2350 When I evaluate the expression, the message @code{"He saw 38 red
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2351 foxes leaping."} appears in my echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2352
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2353 @node set & setq, Summary, Arguments, List Processing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2354 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2355 @section Setting the Value of a Variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2356 @cindex Variable, setting value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2357 @cindex Setting value of variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2358
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2359 @cindex @samp{bind} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2360 There are several ways by which a variable can be given a value. One of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2361 the ways is to use either the function @code{set} or the function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2362 @code{setq}. Another way is to use @code{let} (@pxref{let}). (The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2363 jargon for this process is to @dfn{bind} a variable to a value.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2364
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2365 The following sections not only describe how @code{set} and @code{setq}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2366 work but also illustrate how arguments are passed.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2367
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2368 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2369 * Using set:: Setting values.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2370 * Using setq:: Setting a quoted value.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2371 * Counting:: Using @code{setq} to count.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2372 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2373
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2374 @node Using set, Using setq, set & setq, set & setq
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2375 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2376 @subsection Using @code{set}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2377 @findex set
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2378
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2379 To set the value of the symbol @code{flowers} to the list @code{'(rose
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2380 violet daisy buttercup)}, evaluate the following expression by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2381 positioning the cursor after the expression and typing @kbd{C-x C-e}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2382
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2383 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2384 (set 'flowers '(rose violet daisy buttercup))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2385 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2386
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2387 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2388 The list @code{(rose violet daisy buttercup)} will appear in the echo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2389 area. This is what is @emph{returned} by the @code{set} function. As a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2390 side effect, the symbol @code{flowers} is bound to the list ; that is,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2391 the symbol @code{flowers}, which can be viewed as a variable, is given
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2392 the list as its value. (This process, by the way, illustrates how a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2393 side effect to the Lisp interpreter, setting the value, can be the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2394 primary effect that we humans are interested in. This is because every
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2395 Lisp function must return a value if it does not get an error, but it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2396 will only have a side effect if it is designed to have one.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2397
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2398 After evaluating the @code{set} expression, you can evaluate the symbol
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2399 @code{flowers} and it will return the value you just set. Here is the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2400 symbol. Place your cursor after it and type @kbd{C-x C-e}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2401
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2402 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2403 flowers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2404 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2405
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2406 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2407 When you evaluate @code{flowers}, the list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2408 @code{(rose violet daisy buttercup)} appears in the echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2409
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2410 Incidentally, if you evaluate @code{'flowers}, the variable with a quote
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2411 in front of it, what you will see in the echo area is the symbol itself,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2412 @code{flowers}. Here is the quoted symbol, so you can try this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2413
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2414 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2415 'flowers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2416 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2417
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2418 Note also, that when you use @code{set}, you need to quote both
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2419 arguments to @code{set}, unless you want them evaluated. Since we do
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2420 not want either argument evaluated, neither the variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2421 @code{flowers} nor the list @code{(rose violet daisy buttercup)}, both
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2422 are quoted. (When you use @code{set} without quoting its first
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2423 argument, the first argument is evaluated before anything else is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2424 done. If you did this and @code{flowers} did not have a value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2425 already, you would get an error message that the @samp{Symbol's value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2426 as variable is void}; on the other hand, if @code{flowers} did return
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2427 a value after it was evaluated, the @code{set} would attempt to set
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2428 the value that was returned. There are situations where this is the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2429 right thing for the function to do; but such situations are rare.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2430
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2431 @node Using setq, Counting, Using set, set & setq
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2432 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2433 @subsection Using @code{setq}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2434 @findex setq
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2435
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2436 As a practical matter, you almost always quote the first argument to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2437 @code{set}. The combination of @code{set} and a quoted first argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2438 is so common that it has its own name: the special form @code{setq}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2439 This special form is just like @code{set} except that the first argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2440 is quoted automatically, so you don't need to type the quote mark
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2441 yourself. Also, as an added convenience, @code{setq} permits you to set
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2442 several different variables to different values, all in one expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2443
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2444 To set the value of the variable @code{carnivores} to the list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2445 @code{'(lion tiger leopard)} using @code{setq}, the following expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2446 is used:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2447
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2448 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2449 (setq carnivores '(lion tiger leopard))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2450 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2451
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2452 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2453 This is exactly the same as using @code{set} except the first argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2454 is automatically quoted by @code{setq}. (The @samp{q} in @code{setq}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2455 means @code{quote}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2456
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2457 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2458 With @code{set}, the expression would look like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2459
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2460 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2461 (set 'carnivores '(lion tiger leopard))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2462 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2463
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2464 Also, @code{setq} can be used to assign different values to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2465 different variables. The first argument is bound to the value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2466 of the second argument, the third argument is bound to the value of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2467 fourth argument, and so on. For example, you could use the following to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2468 assign a list of trees to the symbol @code{trees} and a list of herbivores
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2469 to the symbol @code{herbivores}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2470
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2471 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2472 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2473 (setq trees '(pine fir oak maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2474 herbivores '(gazelle antelope zebra))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2475 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2476 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2477
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2478 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2479 (The expression could just as well have been on one line, but it might
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2480 not have fit on a page; and humans find it easier to read nicely
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2481 formatted lists.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2482
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2483 Although I have been using the term `assign', there is another way of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2484 thinking about the workings of @code{set} and @code{setq}; and that is to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2485 say that @code{set} and @code{setq} make the symbol @emph{point} to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2486 list. This latter way of thinking is very common and in forthcoming
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2487 chapters we shall come upon at least one symbol that has `pointer' as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2488 part of its name. The name is chosen because the symbol has a value,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2489 specifically a list, attached to it; or, expressed another way,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2490 the symbol is set to ``point'' to the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2491
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2492 @node Counting, , Using setq, set & setq
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2493 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2494 @subsection Counting
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2495 @cindex Counting
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2496
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2497 Here is an example that shows how to use @code{setq} in a counter. You
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2498 might use this to count how many times a part of your program repeats
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2499 itself. First set a variable to zero; then add one to the number each
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2500 time the program repeats itself. To do this, you need a variable that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2501 serves as a counter, and two expressions: an initial @code{setq}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2502 expression that sets the counter variable to zero; and a second
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2503 @code{setq} expression that increments the counter each time it is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2504 evaluated.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2505
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2506 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2507 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2508 (setq counter 0) ; @r{Let's call this the initializer.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2509
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2510 (setq counter (+ counter 1)) ; @r{This is the incrementer.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2511
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2512 counter ; @r{This is the counter.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2513 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2514 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2515
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2516 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2517 (The text following the @samp{;} are comments. @xref{Change a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2518 defun, , Change a Function Definition}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2519
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2520 If you evaluate the first of these expressions, the initializer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2521 @code{(setq counter 0)}, and then evaluate the third expression,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2522 @code{counter}, the number @code{0} will appear in the echo area. If
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2523 you then evaluate the second expression, the incrementer, @code{(setq
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2524 counter (+ counter 1))}, the counter will get the value 1. So if you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2525 again evaluate @code{counter}, the number @code{1} will appear in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2526 echo area. Each time you evaluate the second expression, the value of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2527 the counter will be incremented.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2528
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2529 When you evaluate the incrementer, @code{(setq counter (+ counter 1))},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2530 the Lisp interpreter first evaluates the innermost list; this is the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2531 addition. In order to evaluate this list, it must evaluate the variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2532 @code{counter} and the number @code{1}. When it evaluates the variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2533 @code{counter}, it receives its current value. It passes this value and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2534 the number @code{1} to the @code{+} which adds them together. The sum
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2535 is then returned as the value of the inner list and passed to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2536 @code{setq} which sets the variable @code{counter} to this new value.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2537 Thus, the value of the variable, @code{counter}, is changed.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2538
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2539 @node Summary, Error Message Exercises, set & setq, List Processing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2540 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2541 @section Summary
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2542
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2543 Learning Lisp is like climbing a hill in which the first part is the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2544 steepest. You have now climbed the most difficult part; what remains
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2545 becomes easier as you progress onwards.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2546
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2547 In summary,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2548
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2549 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2550
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2551 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2552 Lisp programs are made up of expressions, which are lists or single atoms.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2553
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2554 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2555 Lists are made up of zero or more atoms or inner lists, separated by whitespace and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2556 surrounded by parentheses. A list can be empty.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2557
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2558 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2559 Atoms are multi-character symbols, like @code{forward-paragraph}, single
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2560 character symbols like @code{+}, strings of characters between double
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2561 quotation marks, or numbers.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2562
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2563 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2564 A number evaluates to itself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2565
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2566 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2567 A string between double quotes also evaluates to itself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2568
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2569 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2570 When you evaluate a symbol by itself, its value is returned.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2571
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2572 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2573 When you evaluate a list, the Lisp interpreter looks at the first symbol
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2574 in the list and then at the function definition bound to that symbol.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2575 Then the instructions in the function definition are carried out.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2576
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2577 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2578 A single-quote, @code{'}, tells the Lisp interpreter that it should
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2579 return the following expression as written, and not evaluate it as it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2580 would if the quote were not there.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2581
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2582 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2583 Arguments are the information passed to a function. The arguments to a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2584 function are computed by evaluating the rest of the elements of the list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2585 of which the function is the first element.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2586
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2587 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2588 A function always returns a value when it is evaluated (unless it gets
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2589 an error); in addition, it may also carry out some action called a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2590 ``side effect''. In many cases, a function's primary purpose is to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2591 create a side effect.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2592 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2593
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2594 @node Error Message Exercises, , Summary, List Processing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2595 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2596 @section Exercises
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2597
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2598 A few simple exercises:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2599
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2600 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2601 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2602 Generate an error message by evaluating an appropriate symbol that is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2603 not within parentheses.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2604
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2605 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2606 Generate an error message by evaluating an appropriate symbol that is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2607 between parentheses.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2608
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2609 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2610 Create a counter that increments by two rather than one.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2611
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2612 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2613 Write an expression that prints a message in the echo area when
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2614 evaluated.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2615 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2616
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2617 @node Practicing Evaluation, Writing Defuns, List Processing, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2618 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2619 @chapter Practicing Evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2620 @cindex Practicing evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2621 @cindex Evaluation practice
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2622
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2623 Before learning how to write a function definition in Emacs Lisp, it is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2624 useful to spend a little time evaluating various expressions that have
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2625 already been written. These expressions will be lists with the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2626 functions as their first (and often only) element. Since some of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2627 functions associated with buffers are both simple and interesting, we
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2628 will start with those. In this section, we will evaluate a few of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2629 these. In another section, we will study the code of several other
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2630 buffer-related functions, to see how they were written.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2631
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2632 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2633 * How to Evaluate:: Typing editing commands or @kbd{C-x C-e}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2634 causes evaluation.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2635 * Buffer Names:: Buffers and files are different.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2636 * Getting Buffers:: Getting a buffer itself, not merely its name.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2637 * Switching Buffers:: How to change to another buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2638 * Buffer Size & Locations:: Where point is located and the size of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2639 the buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2640 * Evaluation Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2641 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2642
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2643 @node How to Evaluate, Buffer Names, Practicing Evaluation, Practicing Evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2644 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2645 @unnumberedsec How to Evaluate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2646 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2647
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2648 @i{Whenever you give an editing command} to Emacs Lisp, such as the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2649 command to move the cursor or to scroll the screen, @i{you are evaluating
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2650 an expression,} the first element of which is a function. @i{This is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2651 how Emacs works.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2652
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2653 @cindex @samp{interactive function} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2654 @cindex @samp{command} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2655 When you type keys, you cause the Lisp interpreter to evaluate an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2656 expression and that is how you get your results. Even typing plain text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2657 involves evaluating an Emacs Lisp function, in this case, one that uses
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2658 @code{self-insert-command}, which simply inserts the character you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2659 typed. The functions you evaluate by typing keystrokes are called
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2660 @dfn{interactive} functions, or @dfn{commands}; how you make a function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2661 interactive will be illustrated in the chapter on how to write function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2662 definitions. @xref{Interactive, , Making a Function Interactive}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2663
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2664 In addition to typing keyboard commands, we have seen a second way to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2665 evaluate an expression: by positioning the cursor after a list and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2666 typing @kbd{C-x C-e}. This is what we will do in the rest of this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2667 section. There are other ways to evaluate an expression as well; these
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2668 will be described as we come to them.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2669
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2670 Besides being used for practicing evaluation, the functions shown in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2671 next few sections are important in their own right. A study of these
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2672 functions makes clear the distinction between buffers and files, how to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2673 switch to a buffer, and how to determine a location within it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2674
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2675 @node Buffer Names, Getting Buffers, How to Evaluate, Practicing Evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2676 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2677 @section Buffer Names
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2678 @findex buffer-name
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2679 @findex buffer-file-name
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2680
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2681 The two functions, @code{buffer-name} and @code{buffer-file-name}, show
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2682 the difference between a file and a buffer. When you evaluate the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2683 following expression, @code{(buffer-name)}, the name of the buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2684 appears in the echo area. When you evaluate @code{(buffer-file-name)},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2685 the name of the file to which the buffer refers appears in the echo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2686 area. Usually, the name returned by @code{(buffer-name)} is the same as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2687 the name of the file to which it refers, and the name returned by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2688 @code{(buffer-file-name)} is the full path-name of the file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2689
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2690 A file and a buffer are two different entities. A file is information
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2691 recorded permanently in the computer (unless you delete it). A buffer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2692 on the other hand, is information inside of Emacs that will vanish at
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2693 the end of the editing session (or when you kill the buffer). Usually,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2694 a buffer contains information that you have copied from a file; we say
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2695 the buffer is @dfn{visiting} that file. This copy is what you work on
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2696 and modify. Changes to the buffer do not change the file, until you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2697 save the buffer. When you save the buffer, the buffer is copied to the file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2698 and is thus saved permanently.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2699
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2700 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2701 If you are reading this in Info inside of GNU Emacs, you can evaluate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2702 each of the following expressions by positioning the cursor after it and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2703 typing @kbd{C-x C-e}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2704
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2705 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2706 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2707 (buffer-name)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2708
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2709 (buffer-file-name)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2710 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2711 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2712
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2713 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2714 When I do this, @file{"introduction.texinfo"} is the value returned by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2715 evaluating @code{(buffer-name)}, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2716 @file{"/gnu/work/intro/introduction.texinfo"} is the value returned by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2717 evaluating @code{(buffer-file-name)}. The former is the name of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2718 buffer and the latter is the name of the file. (In the expressions, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2719 parentheses tell the Lisp interpreter to treat @code{buffer-name} and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2720 @code{buffer-file-name} as functions; without the parentheses, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2721 interpreter would attempt to evaluate the symbols as variables.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2722 @xref{Variables}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2723
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2724 In spite of the distinction between files and buffers, you will often
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2725 find that people refer to a file when they mean a buffer and vice-versa.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2726 Indeed, most people say, ``I am editing a file,'' rather than saying,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2727 ``I am editing a buffer which I will soon save to a file.'' It is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2728 almost always clear from context what people mean. When dealing with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2729 computer programs, however, it is important to keep the distinction in mind,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2730 since the computer is not as smart as a person.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2731
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2732 @cindex Buffer, history of word
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2733 The word `buffer', by the way, comes from the meaning of the word as a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2734 cushion that deadens the force of a collision. In early computers, a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2735 buffer cushioned the interaction between files and the computer's
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2736 central processing unit. The drums or tapes that held a file and the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2737 central processing unit were pieces of equipment that were very
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2738 different from each other, working at their own speeds, in spurts. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2739 buffer made it possible for them to work together effectively.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2740 Eventually, the buffer grew from being an intermediary, a temporary
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2741 holding place, to being the place where work is done. This
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2742 transformation is rather like that of a small seaport that grew into a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2743 great city: once it was merely the place where cargo was warehoused
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2744 temporarily before being loaded onto ships; then it became a business
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2745 and cultural center in its own right.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2746
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2747 Not all buffers are associated with files. For example, when you start
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2748 an Emacs session by typing the command @code{emacs} alone, without
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2749 naming any files, Emacs will start with the @file{*scratch*} buffer on
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2750 the screen. This buffer is not visiting any file. Similarly, a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2751 @file{*Help*} buffer is not associated with any file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2752
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2753 @cindex @code{nil}, history of word
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2754 If you switch to the @file{*scratch*} buffer, type @code{(buffer-name)},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2755 position the cursor after it, and type @kbd{C-x C-e} to evaluate the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2756 expression, the name @code{"*scratch*"} is returned and will appear in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2757 the echo area. @code{"*scratch*"} is the name of the buffer. However,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2758 if you type @code{(buffer-file-name)} in the @file{*scratch*} buffer and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2759 evaluate that, @code{nil} will appear in the echo area. @code{nil} is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2760 from the Latin word for `nothing'; in this case, it means that the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2761 @file{*scratch*} buffer is not associated with any file. (In Lisp,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2762 @code{nil} is also used to mean `false' and is a synonym for the empty
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2763 list, @code{()}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2764
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2765 Incidentally, if you are in the @file{*scratch*} buffer and want the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2766 value returned by an expression to appear in the @file{*scratch*}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2767 buffer itself rather than in the echo area, type @kbd{C-u C-x C-e}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2768 instead of @kbd{C-x C-e}. This causes the value returned to appear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2769 after the expression. The buffer will look like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2770
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2771 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2772 (buffer-name)"*scratch*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2773 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2774
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2775 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2776 You cannot do this in Info since Info is read-only and it will not allow
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2777 you to change the contents of the buffer. But you can do this in any
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2778 buffer you can edit; and when you write code or documentation (such as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2779 this book), this feature is very useful.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2780
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2781 @node Getting Buffers, Switching Buffers, Buffer Names, Practicing Evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2782 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2783 @section Getting Buffers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2784 @findex current-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2785 @findex other-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2786 @cindex Getting a buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2787
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2788 The @code{buffer-name} function returns the @emph{name} of the buffer;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2789 to get the buffer @emph{itself}, a different function is needed: the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2790 @code{current-buffer} function. If you use this function in code, what
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2791 you get is the buffer itself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2792
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2793 A name and the object or entity to which the name refers are different
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2794 from each other. You are not your name. You are a person to whom
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2795 others refer by name. If you ask to speak to George and someone hands you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2796 a card with the letters @samp{G}, @samp{e}, @samp{o}, @samp{r},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2797 @samp{g}, and @samp{e} written on it, you might be amused, but you would
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2798 not be satisfied. You do not want to speak to the name, but to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2799 person to whom the name refers. A buffer is similar: the name of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2800 scratch buffer is @file{*scratch*}, but the name is not the buffer. To
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2801 get a buffer itself, you need to use a function such as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2802 @code{current-buffer}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2803
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2804 However, there is a slight complication: if you evaluate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2805 @code{current-buffer} in an expression on its own, as we will do here,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2806 what you see is a printed representation of the name of the buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2807 without the contents of the buffer. Emacs works this way for two
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2808 reasons: the buffer may be thousands of lines long---too long to be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2809 conveniently displayed; and, another buffer may have the same contents
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2810 but a different name, and it is important to distinguish between them.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2811
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2812 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2813 Here is an expression containing the function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2814
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2815 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2816 (current-buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2817 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2818
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2819 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2820 If you evaluate the expression in the usual way, @file{#<buffer *info*>}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2821 appears in the echo area. The special format indicates that the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2822 buffer itself is being returned, rather than just its name.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2823
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2824 Incidentally, while you can type a number or symbol into a program, you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2825 cannot do that with the printed representation of a buffer: the only way
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2826 to get a buffer itself is with a function such as @code{current-buffer}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2827
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2828 A related function is @code{other-buffer}. This returns the most
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2829 recently selected buffer other than the one you are in currently. If
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2830 you have recently switched back and forth from the @file{*scratch*}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2831 buffer, @code{other-buffer} will return that buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2832
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2833 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2834 You can see this by evaluating the expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2835
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2836 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2837 (other-buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2838 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2839
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2840 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2841 You should see @file{#<buffer *scratch*>} appear in the echo area, or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2842 the name of whatever other buffer you switched back from most
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2843 recently@footnote{Actually, by default, if the buffer from which you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2844 just switched is visible to you in another window, @code{other-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2845 will choose the most recent buffer that you cannot see; this is a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2846 subtlety that I often forget.}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2847
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2848 @node Switching Buffers, Buffer Size & Locations, Getting Buffers, Practicing Evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2849 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2850 @section Switching Buffers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2851 @findex switch-to-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2852 @findex set-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2853 @cindex Switching to a buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2854
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2855 The @code{other-buffer} function actually provides a buffer when it is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2856 used as an argument to a function that requires one. We can see this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2857 by using @code{other-buffer} and @code{switch-to-buffer} to switch to a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2858 different buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2859
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2860 But first, a brief introduction to the @code{switch-to-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2861 function. When you switched back and forth from Info to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2862 @file{*scratch*} buffer to evaluate @code{(buffer-name)}, you most
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2863 likely typed @kbd{C-x b} and then typed @file{*scratch*}@footnote{Or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2864 rather, to save typing, you probably typed just part of the name, such
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2865 as @code{*sc}, and then pressed your @kbd{TAB} key to cause it to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2866 expand to the full name; and then typed your @kbd{RET} key.} when
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2867 prompted in the minibuffer for the name of the buffer to which you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2868 wanted to switch. The keystrokes, @kbd{C-x b}, cause the Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2869 interpreter to evaluate the interactive function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2870 @code{switch-to-buffer}. As we said before, this is how Emacs works:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2871 different keystrokes call or run different functions. For example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2872 @kbd{C-f} calls @code{forward-char}, @kbd{M-e} calls
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2873 @code{forward-sentence}, and so on.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2874
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2875 By writing @code{switch-to-buffer} in an expression, and giving it a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2876 buffer to switch to, we can switch buffers just the way @kbd{C-x b}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2877 does.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2878
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2879 @need 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2880 Here is the Lisp expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2881
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2882 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2883 (switch-to-buffer (other-buffer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2884 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2885
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2886 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2887 The symbol @code{switch-to-buffer} is the first element of the list,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2888 so the Lisp interpreter will treat it as a function and carry out the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2889 instructions that are attached to it. But before doing that, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2890 interpreter will note that @code{other-buffer} is inside parentheses
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2891 and work on that symbol first. @code{other-buffer} is the first (and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2892 in this case, the only) element of this list, so the Lisp interpreter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2893 calls or runs the function. It returns another buffer. Next, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2894 interpreter runs @code{switch-to-buffer}, passing to it, as an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2895 argument, the other buffer, which is what Emacs will switch to. If
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2896 you are reading this in Info, try this now. Evaluate the expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2897 (To get back, type @kbd{C-x b @key{RET}}.)@footnote{Remember, this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2898 expression will move you to your most recent other buffer that you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2899 cannot see. If you really want to go to your most recently selected
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2900 buffer, even if you can still see it, you need to evaluate the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2901 following more complex expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2902
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2903 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2904 (switch-to-buffer (other-buffer (current-buffer) t))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2905 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2906
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2907 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2908 In this case, the first argument to @code{other-buffer} tells it which
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2909 buffer to skip---the current one---and the second argument tells
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2910 @code{other-buffer} it is OK to switch to a visible buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2911 In regular use, @code{switch-to-buffer} takes you to an invisible
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2912 window since you would most likely use @kbd{C-x o} (@code{other-window})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2913 to go to another visible buffer.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2914
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2915 In the programming examples in later sections of this document, you will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2916 see the function @code{set-buffer} more often than
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2917 @code{switch-to-buffer}. This is because of a difference between
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2918 computer programs and humans: humans have eyes and expect to see the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2919 buffer on which they are working on their computer terminals. This is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2920 so obvious, it almost goes without saying. However, programs do not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2921 have eyes. When a computer program works on a buffer, that buffer does
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2922 not need to be visible on the screen.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2923
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2924 @code{switch-to-buffer} is designed for humans and does two different
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2925 things: it switches the buffer to which Emacs' attention is directed; and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2926 it switches the buffer displayed in the window to the new buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2927 @code{set-buffer}, on the other hand, does only one thing: it switches
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2928 the attention of the computer program to a different buffer. The buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2929 on the screen remains unchanged (of course, normally nothing happens
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2930 there until the command finishes running).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2931
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2932 @cindex @samp{call} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2933 Also, we have just introduced another jargon term, the word @dfn{call}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2934 When you evaluate a list in which the first symbol is a function, you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2935 are calling that function. The use of the term comes from the notion of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2936 the function as an entity that can do something for you if you `call'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2937 it---just as a plumber is an entity who can fix a leak if you call him
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2938 or her.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2939
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2940 @node Buffer Size & Locations, Evaluation Exercise, Switching Buffers, Practicing Evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2941 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2942 @section Buffer Size and the Location of Point
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2943 @cindex Size of buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2944 @cindex Buffer size
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2945 @cindex Point location
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2946 @cindex Location of point
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2947
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2948 Finally, let's look at several rather simple functions,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2949 @code{buffer-size}, @code{point}, @code{point-min}, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2950 @code{point-max}. These give information about the size of a buffer and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2951 the location of point within it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2952
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2953 The function @code{buffer-size} tells you the size of the current
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2954 buffer; that is, the function returns a count of the number of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2955 characters in the buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2956
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2957 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2958 (buffer-size)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2959 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2960
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2961 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2962 You can evaluate this in the usual way, by positioning the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2963 cursor after the expression and typing @kbd{C-x C-e}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2964
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2965 @cindex @samp{point} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2966 In Emacs, the current position of the cursor is called @dfn{point}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2967 The expression @code{(point)} returns a number that tells you where the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2968 cursor is located as a count of the number of characters from the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2969 beginning of the buffer up to point.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2970
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2971 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2972 You can see the character count for point in this buffer by evaluating
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2973 the following expression in the usual way:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2974
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2975 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2976 (point)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2977 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2978
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2979 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2980 As I write this, the value of @code{point} is 65724. The @code{point}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2981 function is frequently used in some of the examples later in this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2982 book.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2983
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2984 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2985 The value of point depends, of course, on its location within the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2986 buffer. If you evaluate point in this spot, the number will be larger:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2987
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2988 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2989 (point)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2990 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2991
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2992 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2993 For me, the value of point in this location is 66043, which means that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2994 there are 319 characters (including spaces) between the two expressions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2995
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2996 @cindex @samp{narrowing} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2997 The function @code{point-min} is somewhat similar to @code{point}, but
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2998 it returns the value of the minimum permissible value of point in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2999 current buffer. This is the number 1 unless @dfn{narrowing} is in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3000 effect. (Narrowing is a mechanism whereby you can restrict yourself,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3001 or a program, to operations on just a part of a buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3002 @xref{Narrowing & Widening, , Narrowing and Widening}.) Likewise, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3003 function @code{point-max} returns the value of the maximum permissible
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3004 value of point in the current buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3005
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3006 @node Evaluation Exercise, , Buffer Size & Locations, Practicing Evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3007 @section Exercise
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3008
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3009 Find a file with which you are working and move towards its middle.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3010 Find its buffer name, file name, length, and your position in the file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3011
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3012 @node Writing Defuns, Buffer Walk Through, Practicing Evaluation, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3013 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3014 @chapter How To Write Function Definitions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3015 @cindex Definition writing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3016 @cindex Function definition writing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3017 @cindex Writing a function definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3018
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3019 When the Lisp interpreter evaluates a list, it looks to see whether the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3020 first symbol on the list has a function definition attached to it; or,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3021 put another way, whether the symbol points to a function definition. If
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3022 it does, the computer carries out the instructions in the definition. A
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3023 symbol that has a function definition is called, simply, a function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3024 (although, properly speaking, the definition is the function and the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3025 symbol refers to it.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3026
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3027 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3028 * Primitive Functions::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3029 * defun:: The @code{defun} special form.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3030 * Install:: Install a function definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3031 * Interactive:: Making a function interactive.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3032 * Interactive Options:: Different options for @code{interactive}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3033 * Permanent Installation:: Installing code permanently.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3034 * let:: Creating and initializing local variables.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3035 * if:: What if?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3036 * else:: If--then--else expressions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3037 * Truth & Falsehood:: What Lisp considers false and true.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3038 * save-excursion:: Keeping track of point, mark, and buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3039 * Review::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3040 * defun Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3041 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3042
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3043 @node Primitive Functions, defun, Writing Defuns, Writing Defuns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3044 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3045 @unnumberedsec An Aside about Primitive Functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3046 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3047 @cindex Primitive functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3048 @cindex Functions, primitive
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3049
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3050 @cindex C language primitives
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3051 @cindex Primitives written in C
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3052 All functions are defined in terms of other functions, except for a few
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3053 @dfn{primitive} functions that are written in the C programming
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3054 language. When you write functions' definitions, you will write them in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3055 Emacs Lisp and use other functions as your building blocks. Some of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3056 functions you will use will themselves be written in Emacs Lisp (perhaps
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3057 by you) and some will be primitives written in C. The primitive
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3058 functions are used exactly like those written in Emacs Lisp and behave
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3059 like them. They are written in C so we can easily run GNU Emacs on any
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3060 computer that has sufficient power and can run C.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3061
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3062 Let me re-emphasize this: when you write code in Emacs Lisp, you do not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3063 distinguish between the use of functions written in C and the use of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3064 functions written in Emacs Lisp. The difference is irrelevant. I
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3065 mention the distinction only because it is interesting to know. Indeed,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3066 unless you investigate, you won't know whether an already-written
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3067 function is written in Emacs Lisp or C.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3068
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3069 @node defun, Install, Primitive Functions, Writing Defuns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3070 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3071 @section The @code{defun} Special Form
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3072 @findex defun
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3073 @cindex Special form of @code{defun}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3074
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3075 @cindex @samp{function definition} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3076 In Lisp, a symbol such as @code{mark-whole-buffer} has code attached to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3077 it that tells the computer what to do when the function is called.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3078 This code is called the @dfn{function definition} and is created by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3079 evaluating a Lisp expression that starts with the symbol @code{defun}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3080 (which is an abbreviation for @emph{define function}). Because
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3081 @code{defun} does not evaluate its arguments in the usual way, it is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3082 called a @dfn{special form}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3083
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3084 In subsequent sections, we will look at function definitions from the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3085 Emacs source code, such as @code{mark-whole-buffer}. In this section,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3086 we will describe a simple function definition so you can see how it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3087 looks. This function definition uses arithmetic because it makes for a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3088 simple example. Some people dislike examples using arithmetic; however,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3089 if you are such a person, do not despair. Hardly any of the code we
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3090 will study in the remainder of this introduction involves arithmetic or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3091 mathematics. The examples mostly involve text in one way or another.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3092
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3093 A function definition has up to five parts following the word
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3094 @code{defun}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3095
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3096 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3097 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3098 The name of the symbol to which the function definition should be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3099 attached.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3100
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3101 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3102 A list of the arguments that will be passed to the function. If no
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3103 arguments will be passed to the function, this is an empty list,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3104 @code{()}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3105
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3106 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3107 Documentation describing the function. (Technically optional, but
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3108 strongly recommended.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3109
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3110 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3111 Optionally, an expression to make the function interactive so you can
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3112 use it by typing @kbd{M-x} and then the name of the function; or by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3113 typing an appropriate key or keychord.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3114
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3115 @cindex @samp{body} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3116 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3117 The code that instructs the computer what to do: the @dfn{body} of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3118 function definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3119 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3120
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3121 It is helpful to think of the five parts of a function definition as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3122 being organized in a template, with slots for each part:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3123
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3124 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3125 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3126 (defun @var{function-name} (@var{arguments}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3127 "@var{optional-documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3128 (interactive @var{argument-passing-info}) ; @r{optional}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3129 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3130 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3131 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3132
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3133 As an example, here is the code for a function that multiplies its
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3134 argument by 7. (This example is not interactive. @xref{Interactive,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3135 , Making a Function Interactive}, for that information.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3136
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3137 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3138 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3139 (defun multiply-by-seven (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3140 "Multiply NUMBER by seven."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3141 (* 7 number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3142 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3143 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3144
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3145 This definition begins with a parenthesis and the symbol @code{defun},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3146 followed by the name of the function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3147
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3148 @cindex @samp{argument list} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3149 The name of the function is followed by a list that contains the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3150 arguments that will be passed to the function. This list is called
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3151 the @dfn{argument list}. In this example, the list has only one
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3152 element, the symbol, @code{number}. When the function is used, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3153 symbol will be bound to the value that is used as the argument to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3154 function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3155
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3156 Instead of choosing the word @code{number} for the name of the argument,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3157 I could have picked any other name. For example, I could have chosen
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3158 the word @code{multiplicand}. I picked the word `number' because it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3159 tells what kind of value is intended for this slot; but I could just as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3160 well have chosen the word `multiplicand' to indicate the role that the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3161 value placed in this slot will play in the workings of the function. I
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3162 could have called it @code{foogle}, but that would have been a bad
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3163 choice because it would not tell humans what it means. The choice of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3164 name is up to the programmer and should be chosen to make the meaning of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3165 the function clear.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3166
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3167 Indeed, you can choose any name you wish for a symbol in an argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3168 list, even the name of a symbol used in some other function: the name
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3169 you use in an argument list is private to that particular definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3170 In that definition, the name refers to a different entity than any use
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3171 of the same name outside the function definition. Suppose you have a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3172 nick-name `Shorty' in your family; when your family members refer to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3173 `Shorty', they mean you. But outside your family, in a movie, for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3174 example, the name `Shorty' refers to someone else. Because a name in an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3175 argument list is private to the function definition, you can change the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3176 value of such a symbol inside the body of a function without changing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3177 its value outside the function. The effect is similar to that produced
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3178 by a @code{let} expression. (@xref{let, , @code{let}}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3179
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3180 @ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3181 Note also that we discuss the word `number' in two different ways: as a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3182 symbol that appears in the code, and as the name of something that will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3183 be replaced by a something else during the evaluation of the function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3184 In the first case, @code{number} is a symbol, not a number; it happens
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3185 that within the function, it is a variable who value is the number in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3186 question, but our primary interest in it is as a symbol. On the other
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3187 hand, when we are talking about the function, our interest is that we
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3188 will substitute a number for the word @var{number}. To keep this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3189 distinction clear, we use different typography for the two
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3190 circumstances. When we talk about this function, or about how it works,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3191 we refer to this number by writing @var{number}. In the function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3192 itself, we refer to it by writing @code{number}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3193 @end ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3194
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3195 The argument list is followed by the documentation string that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3196 describes the function. This is what you see when you type
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3197 @w{@kbd{C-h f}} and the name of a function. Incidentally, when you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3198 write a documentation string like this, you should make the first line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3199 a complete sentence since some commands, such as @code{apropos}, print
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3200 only the first line of a multi-line documentation string. Also, you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3201 should not indent the second line of a documentation string, if you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3202 have one, because that looks odd when you use @kbd{C-h f}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3203 (@code{describe-function}). The documentation string is optional, but
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3204 it is so useful, it should be included in almost every function you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3205 write.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3206
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3207 @findex * @r{(multiplication)}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3208 The third line of the example consists of the body of the function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3209 definition. (Most functions' definitions, of course, are longer than
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3210 this.) In this function, the body is the list, @code{(* 7 number)}, which
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3211 says to multiply the value of @var{number} by 7. (In Emacs Lisp,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3212 @code{*} is the function for multiplication, just as @code{+} is the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3213 function for addition.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3214
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3215 When you use the @code{multiply-by-seven} function, the argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3216 @code{number} evaluates to the actual number you want used. Here is an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3217 example that shows how @code{multiply-by-seven} is used; but don't try
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3218 to evaluate this yet!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3219
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3220 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3221 (multiply-by-seven 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3222 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3223
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3224 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3225 The symbol @code{number}, specified in the function definition in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3226 next section, is given or ``bound to'' the value 3 in the actual use of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3227 the function. Note that although @code{number} was inside parentheses
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3228 in the function definition, the argument passed to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3229 @code{multiply-by-seven} function is not in parentheses. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3230 parentheses are written in the function definition so the computer can
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3231 figure out where the argument list ends and the rest of the function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3232 definition begins.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3233
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3234 If you evaluate this example, you are likely to get an error message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3235 (Go ahead, try it!) This is because we have written the function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3236 definition, but not yet told the computer about the definition---we have
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3237 not yet installed (or `loaded') the function definition in Emacs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3238 Installing a function is the process that tells the Lisp interpreter the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3239 definition of the function. Installation is described in the next
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3240 section.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3241
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3242 @node Install, Interactive, defun, Writing Defuns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3243 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3244 @section Install a Function Definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3245 @cindex Install a Function Definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3246 @cindex Definition installation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3247 @cindex Function definition installation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3248
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3249 If you are reading this inside of Info in Emacs, you can try out the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3250 @code{multiply-by-seven} function by first evaluating the function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3251 definition and then evaluating @code{(multiply-by-seven 3)}. A copy of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3252 the function definition follows. Place the cursor after the last
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3253 parenthesis of the function definition and type @kbd{C-x C-e}. When you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3254 do this, @code{multiply-by-seven} will appear in the echo area. (What
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3255 this means is that when a function definition is evaluated, the value it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3256 returns is the name of the defined function.) At the same time, this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3257 action installs the function definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3258
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3259 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3260 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3261 (defun multiply-by-seven (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3262 "Multiply NUMBER by seven."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3263 (* 7 number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3264 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3265 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3266
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3267 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3268 By evaluating this @code{defun}, you have just installed
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3269 @code{multiply-by-seven} in Emacs. The function is now just as much a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3270 part of Emacs as @code{forward-word} or any other editing function you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3271 use. (@code{multiply-by-seven} will stay installed until you quit
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3272 Emacs. To reload code automatically whenever you start Emacs, see
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3273 @ref{Permanent Installation, , Installing Code Permanently}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3274
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3275
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3276 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3277 * Effect of installation::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3278 * Change a defun:: How to change a function definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3279 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3280
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3281 @node Effect of installation, Change a defun, Install, Install
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3282 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3283 @unnumberedsubsec The effect of installation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3284 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3285
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3286
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3287 You can see the effect of installing @code{multiply-by-seven} by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3288 evaluating the following sample. Place the cursor after the following
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3289 expression and type @kbd{C-x C-e}. The number 21 will appear in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3290 echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3291
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3292 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3293 (multiply-by-seven 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3294 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3295
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3296 If you wish, you can read the documentation for the function by typing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3297 @kbd{C-h f} (@code{describe-function}) and then the name of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3298 function, @code{multiply-by-seven}. When you do this, a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3299 @file{*Help*} window will appear on your screen that says:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3300
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3301 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3302 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3303 multiply-by-seven:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3304 Multiply NUMBER by seven.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3305 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3306 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3307
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3308 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3309 (To return to a single window on your screen, type @kbd{C-x 1}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3310
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3311 @node Change a defun, , Effect of installation, Install
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3312 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3313 @subsection Change a Function Definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3314 @cindex Changing a function definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3315 @cindex Function definition, how to change
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3316 @cindex Definition, how to change
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3317
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3318 If you want to change the code in @code{multiply-by-seven}, just rewrite
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3319 it. To install the new version in place of the old one, evaluate the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3320 function definition again. This is how you modify code in Emacs. It is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3321 very simple.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3322
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3323 As an example, you can change the @code{multiply-by-seven} function to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3324 add the number to itself seven times instead of multiplying the number
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3325 by seven. It produces the same answer, but by a different path. At
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3326 the same time, we will add a comment to the code; a comment is text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3327 that the Lisp interpreter ignores, but that a human reader may find
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3328 useful or enlightening. The comment is that this is the ``second
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3329 version''.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3330
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3331 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3332 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3333 (defun multiply-by-seven (number) ; @r{Second version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3334 "Multiply NUMBER by seven."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3335 (+ number number number number number number number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3336 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3337 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3338
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3339 @cindex Comments in Lisp code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3340 The comment follows a semicolon, @samp{;}. In Lisp, everything on a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3341 line that follows a semicolon is a comment. The end of the line is the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3342 end of the comment. To stretch a comment over two or more lines, begin
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3343 each line with a semicolon.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3344
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3345 @xref{Beginning a .emacs File, , Beginning a @file{.emacs}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3346 File}, and @ref{Comments, , Comments, elisp, The GNU Emacs Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3347 Reference Manual}, for more about comments.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3348
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3349 You can install this version of the @code{multiply-by-seven} function by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3350 evaluating it in the same way you evaluated the first function: place
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3351 the cursor after the last parenthesis and type @kbd{C-x C-e}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3352
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3353 In summary, this is how you write code in Emacs Lisp: you write a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3354 function; install it; test it; and then make fixes or enhancements and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3355 install it again.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3356
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3357 @node Interactive, Interactive Options, Install, Writing Defuns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3358 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3359 @section Make a Function Interactive
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3360 @cindex Interactive functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3361 @findex interactive
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3362
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3363 You make a function interactive by placing a list that begins with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3364 the special form @code{interactive} immediately after the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3365 documentation. A user can invoke an interactive function by typing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3366 @kbd{M-x} and then the name of the function; or by typing the keys to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3367 which it is bound, for example, by typing @kbd{C-n} for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3368 @code{next-line} or @kbd{C-x h} for @code{mark-whole-buffer}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3369
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3370 Interestingly, when you call an interactive function interactively,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3371 the value returned is not automatically displayed in the echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3372 This is because you often call an interactive function for its side
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3373 effects, such as moving forward by a word or line, and not for the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3374 value returned. If the returned value were displayed in the echo area
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3375 each time you typed a key, it would be very distracting.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3376
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3377 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3378 * Interactive multiply-by-seven:: An overview.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3379 * multiply-by-seven in detail:: The interactive version.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3380 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3381
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3382 @node Interactive multiply-by-seven, multiply-by-seven in detail, Interactive, Interactive
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3383 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3384 @unnumberedsubsec An Interactive @code{multiply-by-seven}, An Overview
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3385 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3386
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3387 Both the use of the special form @code{interactive} and one way to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3388 display a value in the echo area can be illustrated by creating an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3389 interactive version of @code{multiply-by-seven}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3390
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3391 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3392 Here is the code:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3393
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3394 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3395 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3396 (defun multiply-by-seven (number) ; @r{Interactive version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3397 "Multiply NUMBER by seven."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3398 (interactive "p")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3399 (message "The result is %d" (* 7 number)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3400 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3401 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3402
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3403 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3404 You can install this code by placing your cursor after it and typing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3405 @kbd{C-x C-e}. The name of the function will appear in your echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3406 Then, you can use this code by typing @kbd{C-u} and a number and then
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3407 typing @kbd{M-x multiply-by-seven} and pressing @key{RET}. The phrase
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3408 @samp{The result is @dots{}} followed by the product will appear in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3409 echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3410
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3411 Speaking more generally, you invoke a function like this in either of two
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3412 ways:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3413
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3414 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3415 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3416 By typing a prefix argument that contains the number to be passed, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3417 then typing @kbd{M-x} and the name of the function, as with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3418 @kbd{C-u 3 M-x forward-sentence}; or,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3419
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3420 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3421 By typing whatever key or keychord the function is bound to, as with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3422 @kbd{C-u 3 M-e}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3423 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3424
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3425 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3426 Both the examples just mentioned work identically to move point forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3427 three sentences. (Since @code{multiply-by-seven} is not bound to a key,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3428 it could not be used as an example of key binding.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3429
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3430 (@xref{Keybindings, , Some Keybindings}, to learn how to bind a command
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3431 to a key.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3432
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3433 A prefix argument is passed to an interactive function by typing the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3434 @key{META} key followed by a number, for example, @kbd{M-3 M-e}, or by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3435 typing @kbd{C-u} and then a number, for example, @kbd{C-u 3 M-e} (if you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3436 type @kbd{C-u} without a number, it defaults to 4).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3437
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3438 @node multiply-by-seven in detail, , Interactive multiply-by-seven, Interactive
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3439 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3440 @subsection An Interactive @code{multiply-by-seven}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3441
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3442 Let's look at the use of the special form @code{interactive} and then at
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3443 the function @code{message} in the interactive version of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3444 @code{multiply-by-seven}. You will recall that the function definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3445 looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3446
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3447 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3448 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3449 (defun multiply-by-seven (number) ; @r{Interactive version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3450 "Multiply NUMBER by seven."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3451 (interactive "p")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3452 (message "The result is %d" (* 7 number)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3453 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3454 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3455
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3456 In this function, the expression, @code{(interactive "p")}, is a list of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3457 two elements. The @code{"p"} tells Emacs to pass the prefix argument to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3458 the function and use its value for the argument of the function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3459
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3460 @need 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3461 The argument will be a number. This means that the symbol
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3462 @code{number} will be bound to a number in the line:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3463
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3464 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3465 (message "The result is %d" (* 7 number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3466 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3467
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3468 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3469 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3470 For example, if your prefix argument is 5, the Lisp interpreter will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3471 evaluate the line as if it were:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3472
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3473 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3474 (message "The result is %d" (* 7 5))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3475 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3476
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3477 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3478 (If you are reading this in GNU Emacs, you can evaluate this expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3479 yourself.) First, the interpreter will evaluate the inner list, which
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3480 is @code{(* 7 5)}. This returns a value of 35. Next, it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3481 will evaluate the outer list, passing the values of the second and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3482 subsequent elements of the list to the function @code{message}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3483
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3484 As we have seen, @code{message} is an Emacs Lisp function especially
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3485 designed for sending a one line message to a user. (@xref{message, , The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3486 @code{message} function}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3487 In summary, the @code{message} function prints its first argument in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3488 echo area as is, except for occurrences of @samp{%d}, @samp{%s}, or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3489 @samp{%c}. When it sees one of these control sequences, the function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3490 looks to the second and subsequent arguments and prints the value of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3491 argument in the location in the string where the control sequence is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3492 located.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3493
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3494 In the interactive @code{multiply-by-seven} function, the control string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3495 is @samp{%d}, which requires a number, and the value returned by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3496 evaluating @code{(* 7 5)} is the number 35. Consequently, the number 35
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3497 is printed in place of the @samp{%d} and the message is @samp{The result
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3498 is 35}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3499
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3500 (Note that when you call the function @code{multiply-by-seven}, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3501 message is printed without quotes, but when you call @code{message}, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3502 text is printed in double quotes. This is because the value returned by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3503 @code{message} is what appears in the echo area when you evaluate an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3504 expression whose first element is @code{message}; but when embedded in a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3505 function, @code{message} prints the text as a side effect without
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3506 quotes.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3507
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3508 @node Interactive Options, Permanent Installation, Interactive, Writing Defuns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3509 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3510 @section Different Options for @code{interactive}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3511 @cindex Options for @code{interactive}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3512 @cindex Interactive options
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3513
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3514 In the example, @code{multiply-by-seven} used @code{"p"} as the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3515 argument to @code{interactive}. This argument told Emacs to interpret
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3516 your typing either @kbd{C-u} followed by a number or @key{META}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3517 followed by a number as a command to pass that number to the function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3518 as its argument. Emacs has more than twenty characters predefined for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3519 use with @code{interactive}. In almost every case, one of these
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3520 options will enable you to pass the right information interactively to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3521 a function. (@xref{Interactive Codes, , Code Characters for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3522 @code{interactive}, elisp, The GNU Emacs Lisp Reference Manual}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3523
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3524 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3525 For example, the character @samp{r} causes Emacs to pass the beginning
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3526 and end of the region (the current values of point and mark) to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3527 function as two separate arguments. It is used as follows:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3528
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3529 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3530 (interactive "r")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3531 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3532
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3533 On the other hand, a @samp{B} tells Emacs to ask for the name of a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3534 buffer that will be passed to the function. When it sees a @samp{B},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3535 Emacs will ask for the name by prompting the user in the minibuffer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3536 using a string that follows the @samp{B}, as in @code{"BAppend to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3537 buffer:@: "}. Not only will Emacs prompt for the name, but Emacs will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3538 complete the name if you type enough of it and press @key{TAB}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3539
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3540 A function with two or more arguments can have information passed to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3541 each argument by adding parts to the string that follows
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3542 @code{interactive}. When you do this, the information is passed to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3543 each argument in the same order it is specified in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3544 @code{interactive} list. In the string, each part is separated from
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3545 the next part by a @samp{\n}, which is a newline. For example, you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3546 could follow @code{"BAppend to buffer:@: "} with a @samp{\n}) and an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3547 @samp{r}. This would cause Emacs to pass the values of point and mark
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3548 to the function as well as prompt you for the buffer---three arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3549 in all.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3550
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3551 In this case, the function definition would look like the following,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3552 where @code{buffer}, @code{start}, and @code{end} are the symbols to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3553 which @code{interactive} binds the buffer and the current values of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3554 beginning and ending of the region:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3555
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3556 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3557 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3558 (defun @var{name-of-function} (buffer start end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3559 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3560 (interactive "BAppend to buffer:@: \nr")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3561 @var{body-of-function}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3562 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3563 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3564
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3565 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3566 (The space after the colon in the prompt makes it look better when you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3567 are prompted. The @code{append-to-buffer} function looks exactly like
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3568 this. @xref{append-to-buffer, , The Definition of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3569 @code{append-to-buffer}}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3570
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3571 If a function does not have arguments, then @code{interactive} does not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3572 require any. Such a function contains the simple expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3573 @code{(interactive)}. The @code{mark-whole-buffer} function is like
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3574 this.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3575
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3576 Alternatively, if the special letter-codes are not right for your
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3577 application, you can pass your own arguments to @code{interactive} as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3578 a list. @xref{interactive, , Using @code{Interactive}, elisp, The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3579 GNU Emacs Lisp Reference Manual}, for more information about this advanced
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3580 technique.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3581
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3582 @node Permanent Installation, let, Interactive Options, Writing Defuns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3583 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3584 @section Install Code Permanently
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3585 @cindex Install code permanently
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3586 @cindex Permanent code installation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3587 @cindex Code installation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3588
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3589 When you install a function definition by evaluating it, it will stay
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3590 installed until you quit Emacs. The next time you start a new session
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3591 of Emacs, the function will not be installed unless you evaluate the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3592 function definition again.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3593
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3594 At some point, you may want to have code installed automatically
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3595 whenever you start a new session of Emacs. There are several ways of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3596 doing this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3597
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3598 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3599 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3600 If you have code that is just for yourself, you can put the code for the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3601 function definition in your @file{.emacs} initialization file. When you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3602 start Emacs, your @file{.emacs} file is automatically evaluated and all
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3603 the function definitions within it are installed.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3604 @xref{Emacs Initialization, , Your @file{.emacs} File}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3605
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3606 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3607 Alternatively, you can put the function definitions that you want
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3608 installed in one or more files of their own and use the @code{load}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3609 function to cause Emacs to evaluate and thereby install each of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3610 functions in the files.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3611 @xref{Loading Files, , Loading Files}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3612
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3613 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3614 On the other hand, if you have code that your whole site will use, it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3615 is usual to put it in a file called @file{site-init.el} that is loaded
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3616 when Emacs is built. This makes the code available to everyone who
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3617 uses your machine. (See the @file{INSTALL} file that is part of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3618 Emacs distribution.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3619 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3620
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3621 Finally, if you have code that everyone who uses Emacs may want, you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3622 can post it on a computer network or send a copy to the Free Software
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3623 Foundation. (When you do this, please license the code and its
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3624 documentation under a license that permits other people to run, copy,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3625 study, modify, and redistribute the code and which protects you from
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3626 having your work taken from you.) If you send a copy of your code to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3627 the Free Software Foundation, and properly protect yourself and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3628 others, it may be included in the next release of Emacs. In large
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3629 part, this is how Emacs has grown over the past years, by donations.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3630
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3631 @node let, if, Permanent Installation, Writing Defuns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3632 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3633 @section @code{let}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3634 @findex let
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3635
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3636 The @code{let} expression is a special form in Lisp that you will need
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3637 to use in most function definitions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3638
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3639 @code{let} is used to attach or bind a symbol to a value in such a way
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3640 that the Lisp interpreter will not confuse the variable with a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3641 variable of the same name that is not part of the function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3642
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3643 To understand why the @code{let} special form is necessary, consider
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3644 the situation in which you own a home that you generally refer to as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3645 `the house', as in the sentence, ``The house needs painting.'' If you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3646 are visiting a friend and your host refers to `the house', he is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3647 likely to be referring to @emph{his} house, not yours, that is, to a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3648 different house.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3649
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3650 If your friend is referring to his house and you think he is referring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3651 to your house, you may be in for some confusion. The same thing could
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3652 happen in Lisp if a variable that is used inside of one function has
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3653 the same name as a variable that is used inside of another function,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3654 and the two are not intended to refer to the same value. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3655 @code{let} special form prevents this kind of confusion.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3656
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3657 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3658 * Prevent confusion::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3659 * Parts of let Expression::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3660 * Sample let Expression::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3661 * Uninitialized let Variables::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3662 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3663
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3664 @node Prevent confusion, Parts of let Expression, let, let
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3665 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3666 @unnumberedsubsec @code{let} Prevents Confusion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3667 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3668
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3669 @cindex @samp{local variable} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3670 The @code{let} special form prevents confusion. @code{let} creates a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3671 name for a @dfn{local variable} that overshadows any use of the same
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3672 name outside the @code{let} expression. This is like understanding
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3673 that whenever your host refers to `the house', he means his house, not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3674 yours. (Symbols used in argument lists work the same way.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3675 @xref{defun, , The @code{defun} Special Form}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3676
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3677 Local variables created by a @code{let} expression retain their value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3678 @emph{only} within the @code{let} expression itself (and within
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3679 expressions called within the @code{let} expression); the local
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3680 variables have no effect outside the @code{let} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3681
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3682 Another way to think about @code{let} is that it is like a @code{setq}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3683 that is temporary and local. The values set by @code{let} are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3684 automatically undone when the @code{let} is finished. The setting
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3685 only effects expressions that are inside the bounds of the @code{let}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3686 expression. In computer science jargon, we would say ``the binding of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3687 a symbol is visible only in functions called in the @code{let} form;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3688 in Emacs Lisp, scoping is dynamic, not lexical.''
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3689
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3690 @code{let} can create more than one variable at once. Also,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3691 @code{let} gives each variable it creates an initial value, either a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3692 value specified by you, or @code{nil}. (In the jargon, this is called
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3693 `binding the variable to the value'.) After @code{let} has created
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3694 and bound the variables, it executes the code in the body of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3695 @code{let}, and returns the value of the last expression in the body,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3696 as the value of the whole @code{let} expression. (`Execute' is a jargon
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3697 term that means to evaluate a list; it comes from the use of the word
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3698 meaning `to give practical effect to' (@cite{Oxford English
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3699 Dictionary}). Since you evaluate an expression to perform an action,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3700 `execute' has evolved as a synonym to `evaluate'.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3701
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3702 @node Parts of let Expression, Sample let Expression, Prevent confusion, let
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3703 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3704 @subsection The Parts of a @code{let} Expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3705 @cindex @code{let} expression, parts of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3706 @cindex Parts of @code{let} expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3707
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3708 @cindex @samp{varlist} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3709 A @code{let} expression is a list of three parts. The first part is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3710 the symbol @code{let}. The second part is a list, called a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3711 @dfn{varlist}, each element of which is either a symbol by itself or a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3712 two-element list, the first element of which is a symbol. The third
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3713 part of the @code{let} expression is the body of the @code{let}. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3714 body usually consists of one or more lists.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3715
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3716 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3717 A template for a @code{let} expression looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3718
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3719 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3720 (let @var{varlist} @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3721 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3722
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3723 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3724 The symbols in the varlist are the variables that are given initial
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3725 values by the @code{let} special form. Symbols by themselves are given
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3726 the initial value of @code{nil}; and each symbol that is the first
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3727 element of a two-element list is bound to the value that is returned
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3728 when the Lisp interpreter evaluates the second element.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3729
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3730 Thus, a varlist might look like this: @code{(thread (needles 3))}. In
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3731 this case, in a @code{let} expression, Emacs binds the symbol
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3732 @code{thread} to an initial value of @code{nil}, and binds the symbol
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3733 @code{needles} to an initial value of 3.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3734
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3735 When you write a @code{let} expression, what you do is put the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3736 appropriate expressions in the slots of the @code{let} expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3737 template.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3738
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3739 If the varlist is composed of two-element lists, as is often the case,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3740 the template for the @code{let} expression looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3741
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3742 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3743 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3744 (let ((@var{variable} @var{value})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3745 (@var{variable} @var{value})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3746 @dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3747 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3748 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3749 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3750
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3751 @node Sample let Expression, Uninitialized let Variables, Parts of let Expression, let
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3752 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3753 @subsection Sample @code{let} Expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3754 @cindex Sample @code{let} expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3755 @cindex @code{let} expression sample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3756
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3757 The following expression creates and gives initial values
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3758 to the two variables @code{zebra} and @code{tiger}. The body of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3759 @code{let} expression is a list which calls the @code{message} function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3760
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3761 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3762 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3763 (let ((zebra 'stripes)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3764 (tiger 'fierce))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3765 (message "One kind of animal has %s and another is %s."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3766 zebra tiger))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3767 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3768 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3769
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3770 Here, the varlist is @code{((zebra 'stripes) (tiger 'fierce))}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3771
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3772 The two variables are @code{zebra} and @code{tiger}. Each variable is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3773 the first element of a two-element list and each value is the second
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3774 element of its two-element list. In the varlist, Emacs binds the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3775 variable @code{zebra} to the value @code{stripes}, and binds the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3776 variable @code{tiger} to the value @code{fierce}. In this example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3777 both values are symbols preceded by a quote. The values could just as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3778 well have been another list or a string. The body of the @code{let}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3779 follows after the list holding the variables. In this example, the body
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3780 is a list that uses the @code{message} function to print a string in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3781 the echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3782
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3783 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3784 You may evaluate the example in the usual fashion, by placing the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3785 cursor after the last parenthesis and typing @kbd{C-x C-e}. When you do
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3786 this, the following will appear in the echo area:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3787
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3788 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3789 "One kind of animal has stripes and another is fierce."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3790 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3791
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3792 As we have seen before, the @code{message} function prints its first
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3793 argument, except for @samp{%s}. In this example, the value of the variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3794 @code{zebra} is printed at the location of the first @samp{%s} and the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3795 value of the variable @code{tiger} is printed at the location of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3796 second @samp{%s}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3797
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3798 @node Uninitialized let Variables, , Sample let Expression, let
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3799 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3800 @subsection Uninitialized Variables in a @code{let} Statement
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3801 @cindex Uninitialized @code{let} variables
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3802 @cindex @code{let} variables uninitialized
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3803
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3804 If you do not bind the variables in a @code{let} statement to specific
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3805 initial values, they will automatically be bound to an initial value of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3806 @code{nil}, as in the following expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3807
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3808 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3809 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3810 (let ((birch 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3811 pine
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3812 fir
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3813 (oak 'some))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3814 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3815 "Here are %d variables with %s, %s, and %s value."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3816 birch pine fir oak))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3817 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3818 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3819
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3820 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3821 Here, the varlist is @code{((birch 3) pine fir (oak 'some))}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3822
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3823 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3824 If you evaluate this expression in the usual way, the following will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3825 appear in your echo area:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3826
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3827 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3828 "Here are 3 variables with nil, nil, and some value."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3829 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3830
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3831 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3832 In this example, Emacs binds the symbol @code{birch} to the number 3,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3833 binds the symbols @code{pine} and @code{fir} to @code{nil}, and binds
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3834 the symbol @code{oak} to the value @code{some}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3835
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3836 Note that in the first part of the @code{let}, the variables @code{pine}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3837 and @code{fir} stand alone as atoms that are not surrounded by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3838 parentheses; this is because they are being bound to @code{nil}, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3839 empty list. But @code{oak} is bound to @code{some} and so is a part of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3840 the list @code{(oak 'some)}. Similarly, @code{birch} is bound to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3841 number 3 and so is in a list with that number. (Since a number
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3842 evaluates to itself, the number does not need to be quoted. Also, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3843 number is printed in the message using a @samp{%d} rather than a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3844 @samp{%s}.) The four variables as a group are put into a list to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3845 delimit them from the body of the @code{let}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3846
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3847 @node if, else, let, Writing Defuns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3848 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3849 @section The @code{if} Special Form
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3850 @findex if
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3851 @cindex Conditional with @code{if}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3852
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3853 A third special form, in addition to @code{defun} and @code{let}, is the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3854 conditional @code{if}. This form is used to instruct the computer to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3855 make decisions. You can write function definitions without using
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3856 @code{if}, but it is used often enough, and is important enough, to be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3857 included here. It is used, for example, in the code for the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3858 function @code{beginning-of-buffer}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3859
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3860 The basic idea behind an @code{if}, is that ``@emph{if} a test is true,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3861 @emph{then} an expression is evaluated.'' If the test is not true, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3862 expression is not evaluated. For example, you might make a decision
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3863 such as, ``if it is warm and sunny, then go to the beach!''
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3864
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3865 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3866 * if in more detail::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3867 * type-of-animal in detail:: An example of an @code{if} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3868 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3869
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3870 @node if in more detail, type-of-animal in detail, if, if
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3871 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3872 @unnumberedsubsec @code{if} in more detail
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3873 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3874
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3875 @cindex @samp{if-part} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3876 @cindex @samp{then-part} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3877 An @code{if} expression written in Lisp does not use the word `then';
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3878 the test and the action are the second and third elements of the list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3879 whose first element is @code{if}. Nonetheless, the test part of an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3880 @code{if} expression is often called the @dfn{if-part} and the second
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3881 argument is often called the @dfn{then-part}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3882
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3883 Also, when an @code{if} expression is written, the true-or-false-test
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3884 is usually written on the same line as the symbol @code{if}, but the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3885 action to carry out if the test is true, the ``then-part'', is written
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3886 on the second and subsequent lines. This makes the @code{if}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3887 expression easier to read.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3888
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3889 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3890 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3891 (if @var{true-or-false-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3892 @var{action-to-carry-out-if-test-is-true})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3893 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3894 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3895
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3896 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3897 The true-or-false-test will be an expression that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3898 is evaluated by the Lisp interpreter.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3899
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3900 Here is an example that you can evaluate in the usual manner. The test
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3901 is whether the number 5 is greater than the number 4. Since it is, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3902 message @samp{5 is greater than 4!} will be printed.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3903
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3904 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3905 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3906 (if (> 5 4) ; @r{if-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3907 (message "5 is greater than 4!")) ; @r{then-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3908 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3909 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3910
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3911 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3912 (The function @code{>} tests whether its first argument is greater than
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3913 its second argument and returns true if it is.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3914 @findex > (greater than)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3915
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3916 Of course, in actual use, the test in an @code{if} expression will not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3917 be fixed for all time as it is by the expression @code{(> 5 4)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3918 Instead, at least one of the variables used in the test will be bound to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3919 a value that is not known ahead of time. (If the value were known ahead
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3920 of time, we would not need to run the test!)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3921
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3922 For example, the value may be bound to an argument of a function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3923 definition. In the following function definition, the character of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3924 animal is a value that is passed to the function. If the value bound to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3925 @code{characteristic} is @code{fierce}, then the message, @samp{It's a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3926 tiger!} will be printed; otherwise, @code{nil} will be returned.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3927
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3928 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3929 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3930 (defun type-of-animal (characteristic)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3931 "Print message in echo area depending on CHARACTERISTIC.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3932 If the CHARACTERISTIC is the symbol `fierce',
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3933 then warn of a tiger."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3934 (if (equal characteristic 'fierce)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3935 (message "It's a tiger!")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3936 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3937 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3938
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3939 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3940 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3941 If you are reading this inside of GNU Emacs, you can evaluate the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3942 function definition in the usual way to install it in Emacs, and then you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3943 can evaluate the following two expressions to see the results:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3944
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3945 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3946 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3947 (type-of-animal 'fierce)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3948
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3949 (type-of-animal 'zebra)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3950
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3951 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3952 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3953
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3954 @c Following sentences rewritten to prevent overfull hbox.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3955 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3956 When you evaluate @code{(type-of-animal 'fierce)}, you will see the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3957 following message printed in the echo area: @code{"It's a tiger!"}; and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3958 when you evaluate @code{(type-of-animal 'zebra)} you will see @code{nil}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3959 printed in the echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3960
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3961 @node type-of-animal in detail, , if in more detail, if
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3962 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3963 @subsection The @code{type-of-animal} Function in Detail
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3964
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3965 Let's look at the @code{type-of-animal} function in detail.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3966
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3967 The function definition for @code{type-of-animal} was written by filling
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3968 the slots of two templates, one for a function definition as a whole, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3969 a second for an @code{if} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3970
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3971 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3972 The template for every function that is not interactive is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3973
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3974 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3975 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3976 (defun @var{name-of-function} (@var{argument-list})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3977 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3978 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3979 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3980 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3981
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3982 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3983 The parts of the function that match this template look like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3984
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3985 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3986 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3987 (defun type-of-animal (characteristic)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3988 "Print message in echo area depending on CHARACTERISTIC.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3989 If the CHARACTERISTIC is the symbol `fierce',
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3990 then warn of a tiger."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3991 @var{body: the} @code{if} @var{expression})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3992 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3993 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3994
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3995 The name of function is @code{type-of-animal}; it is passed the value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3996 of one argument. The argument list is followed by a multi-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3997 documentation string. The documentation string is included in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3998 example because it is a good habit to write documentation string for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3999 every function definition. The body of the function definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4000 consists of the @code{if} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4001
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4002 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4003 The template for an @code{if} expression looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4004
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4005 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4006 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4007 (if @var{true-or-false-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4008 @var{action-to-carry-out-if-the-test-returns-true})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4009 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4010 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4011
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4012 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4013 In the @code{type-of-animal} function, the code for the @code{if}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4014 looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4015
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4016 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4017 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4018 (if (equal characteristic 'fierce)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4019 (message "It's a tiger!")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4020 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4021 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4022
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4023 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4024 Here, the true-or-false-test is the expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4025
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4026 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4027 (equal characteristic 'fierce)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4028 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4029
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4030 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4031 In Lisp, @code{equal} is a function that determines whether its first
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4032 argument is equal to its second argument. The second argument is the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4033 quoted symbol @code{'fierce} and the first argument is the value of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4034 symbol @code{characteristic}---in other words, the argument passed to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4035 this function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4036
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4037 In the first exercise of @code{type-of-animal}, the argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4038 @code{fierce} is passed to @code{type-of-animal}. Since @code{fierce}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4039 is equal to @code{fierce}, the expression, @code{(equal characteristic
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4040 'fierce)}, returns a value of true. When this happens, the @code{if}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4041 evaluates the second argument or then-part of the @code{if}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4042 @code{(message "It's tiger!")}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4043
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4044 On the other hand, in the second exercise of @code{type-of-animal}, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4045 argument @code{zebra} is passed to @code{type-of-animal}. @code{zebra}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4046 is not equal to @code{fierce}, so the then-part is not evaluated and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4047 @code{nil} is returned by the @code{if} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4048
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4049 @node else, Truth & Falsehood, if, Writing Defuns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4050 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4051 @section If--then--else Expressions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4052 @cindex Else
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4053
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4054 An @code{if} expression may have an optional third argument, called
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4055 the @dfn{else-part}, for the case when the true-or-false-test returns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4056 false. When this happens, the second argument or then-part of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4057 overall @code{if} expression is @emph{not} evaluated, but the third or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4058 else-part @emph{is} evaluated. You might think of this as the cloudy
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4059 day alternative for the decision `if it is warm and sunny, then go to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4060 the beach, else read a book!''.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4061
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4062 The word ``else'' is not written in the Lisp code; the else-part of an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4063 @code{if} expression comes after the then-part. In the written Lisp, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4064 else-part is usually written to start on a line of its own and is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4065 indented less than the then-part:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4066
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4067 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4068 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4069 (if @var{true-or-false-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4070 @var{action-to-carry-out-if-the-test-returns-true}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4071 @var{action-to-carry-out-if-the-test-returns-false})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4072 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4073 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4074
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4075 For example, the following @code{if} expression prints the message @samp{4
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4076 is not greater than 5!} when you evaluate it in the usual way:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4077
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4078 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4079 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4080 (if (> 4 5) ; @r{if-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4081 (message "5 is greater than 4!") ; @r{then-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4082 (message "4 is not greater than 5!")) ; @r{else-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4083 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4084 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4085
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4086 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4087 Note that the different levels of indentation make it easy to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4088 distinguish the then-part from the else-part. (GNU Emacs has several
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4089 commands that automatically indent @code{if} expressions correctly.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4090 @xref{Typing Lists, , GNU Emacs Helps You Type Lists}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4091
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4092 We can extend the @code{type-of-animal} function to include an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4093 else-part by simply incorporating an additional part to the @code{if}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4094 expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4095
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4096 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4097 You can see the consequences of doing this if you evaluate the following
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4098 version of the @code{type-of-animal} function definition to install it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4099 and then evaluate the two subsequent expressions to pass different
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4100 arguments to the function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4101
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4102 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4103 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4104 (defun type-of-animal (characteristic) ; @r{Second version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4105 "Print message in echo area depending on CHARACTERISTIC.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4106 If the CHARACTERISTIC is the symbol `fierce',
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4107 then warn of a tiger;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4108 else say it's not fierce."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4109 (if (equal characteristic 'fierce)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4110 (message "It's a tiger!")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4111 (message "It's not fierce!")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4112 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4113 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4114 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4115
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4116 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4117 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4118 (type-of-animal 'fierce)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4119
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4120 (type-of-animal 'zebra)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4121
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4122 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4123 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4124
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4125 @c Following sentence rewritten to prevent overfull hbox.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4126 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4127 When you evaluate @code{(type-of-animal 'fierce)}, you will see the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4128 following message printed in the echo area: @code{"It's a tiger!"}; but
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4129 when you evaluate @code{(type-of-animal 'zebra)}, you will see
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4130 @code{"It's not fierce!"}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4131
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4132 (Of course, if the @var{characteristic} were @code{ferocious}, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4133 message @code{"It's not fierce!"} would be printed; and it would be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4134 misleading! When you write code, you need to take into account the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4135 possibility that some such argument will be tested by the @code{if} and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4136 write your program accordingly.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4137
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4138 @node Truth & Falsehood, save-excursion, else, Writing Defuns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4139 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4140 @section Truth and Falsehood in Emacs Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4141 @cindex Truth and falsehood in Emacs Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4142 @cindex Falsehood and truth in Emacs Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4143 @findex nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4144
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4145 There is an important aspect to the truth test in an @code{if}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4146 expression. So far, we have spoken of `true' and `false' as values of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4147 predicates as if they were new kinds of Emacs Lisp objects. In fact,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4148 `false' is just our old friend @code{nil}. Anything else---anything
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4149 at all---is `true'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4150
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4151 The expression that tests for truth is interpreted as @dfn{true}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4152 if the result of evaluating it is a value that is not @code{nil}. In
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4153 other words, the result of the test is considered true if the value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4154 returned is a number such as 47, a string such as @code{"hello"}, or a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4155 symbol (other than @code{nil}) such as @code{flowers}, or a list, or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4156 even a buffer!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4157
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4158 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4159 * nil explained:: @code{nil} has two meanings.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4160 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4161
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4162 @node nil explained, , Truth & Falsehood, Truth & Falsehood
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4163 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4164 @unnumberedsubsec An explanation of @code{nil}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4165 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4166
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4167 Before illustrating a test for truth, we need an explanation of @code{nil}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4168
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4169 In Emacs Lisp, the symbol @code{nil} has two meanings. First, it means the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4170 empty list. Second, it means false and is the value returned when a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4171 true-or-false-test tests false. @code{nil} can be written as an empty
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4172 list, @code{()}, or as @code{nil}. As far as the Lisp interpreter is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4173 concerned, @code{()} and @code{nil} are the same. Humans, however, tend
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4174 to use @code{nil} for false and @code{()} for the empty list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4175
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4176 In Emacs Lisp, any value that is not @code{nil}---is not the empty
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4177 list---is considered true. This means that if an evaluation returns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4178 something that is not an empty list, an @code{if} expression will test
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4179 true. For example, if a number is put in the slot for the test, it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4180 will be evaluated and will return itself, since that is what numbers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4181 do when evaluated. In this conditional, the @code{if} expression will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4182 test true. The expression tests false only when @code{nil}, an empty
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4183 list, is returned by evaluating the expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4184
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4185 You can see this by evaluating the two expressions in the following examples.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4186
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4187 In the first example, the number 4 is evaluated as the test in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4188 @code{if} expression and returns itself; consequently, the then-part
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4189 of the expression is evaluated and returned: @samp{true} appears in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4190 the echo area. In the second example, the @code{nil} indicates false;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4191 consequently, the else-part of the expression is evaluated and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4192 returned: @samp{false} appears in the echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4193
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4194 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4195 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4196 (if 4
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4197 'true
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4198 'false)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4199 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4201 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4202 (if nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4203 'true
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4204 'false)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4205 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4206 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4207
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4208 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4209 Incidentally, if some other useful value is not available for a test that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4210 returns true, then the Lisp interpreter will return the symbol @code{t}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4211 for true. For example, the expression @code{(> 5 4)} returns @code{t}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4212 when evaluated, as you can see by evaluating it in the usual way:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4213
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4214 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4215 (> 5 4)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4216 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4217
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4218 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4219 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4220 On the other hand, this function returns @code{nil} if the test is false.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4221
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4222 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4223 (> 4 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4224 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4225
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4226 @node save-excursion, Review, Truth & Falsehood, Writing Defuns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4227 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4228 @section @code{save-excursion}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4229 @findex save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4230 @cindex Region, what it is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4231 @cindex Preserving point, mark, and buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4232 @cindex Point, mark, buffer preservation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4233 @findex point
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4234 @findex mark
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4235
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4236 The @code{save-excursion} function is the fourth and final special form
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4237 that we will discuss in this chapter.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4238
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4239 In Emacs Lisp programs used for editing, the @code{save-excursion}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4240 function is very common. It saves the location of point and mark,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4241 executes the body of the function, and then restores point and mark to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4242 their previous positions if their locations were changed. Its primary
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4243 purpose is to keep the user from being surprised and disturbed by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4244 unexpected movement of point or mark.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4245
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4246 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4247 * Point and mark:: A review of various locations.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4248 * Template for save-excursion::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4249 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4251 @node Point and mark, Template for save-excursion, save-excursion, save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4252 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4253 @unnumberedsubsec Point and Mark
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4254 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4255
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4256 Before discussing @code{save-excursion}, however, it may be useful
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4257 first to review what point and mark are in GNU Emacs. @dfn{Point} is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4258 the current location of the cursor. Wherever the cursor
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4259 is, that is point. More precisely, on terminals where the cursor
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4260 appears to be on top of a character, point is immediately before the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4261 character. In Emacs Lisp, point is an integer. The first character in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4262 a buffer is number one, the second is number two, and so on. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4263 function @code{point} returns the current position of the cursor as a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4264 number. Each buffer has its own value for point.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4265
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4266 The @dfn{mark} is another position in the buffer; its value can be set
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4267 with a command such as @kbd{C-@key{SPC}} (@code{set-mark-command}). If
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4268 a mark has been set, you can use the command @kbd{C-x C-x}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4269 (@code{exchange-point-and-mark}) to cause the cursor to jump to the mark
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4270 and set the mark to be the previous position of point. In addition, if
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4271 you set another mark, the position of the previous mark is saved in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4272 mark ring. Many mark positions can be saved this way. You can jump the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4273 cursor to a saved mark by typing @kbd{C-u C-@key{SPC}} one or more
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4274 times.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4275
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4276 The part of the buffer between point and mark is called @dfn{the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4277 region}. Numerous commands work on the region, including
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4278 @code{center-region}, @code{count-lines-region}, @code{kill-region}, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4279 @code{print-region}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4280
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4281 The @code{save-excursion} special form saves the locations of point and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4282 mark and restores those positions after the code within the body of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4283 special form is evaluated by the Lisp interpreter. Thus, if point were
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4284 in the beginning of a piece of text and some code moved point to the end
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4285 of the buffer, the @code{save-excursion} would put point back to where
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4286 it was before, after the expressions in the body of the function were
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4287 evaluated.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4288
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4289 In Emacs, a function frequently moves point as part of its internal
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4290 workings even though a user would not expect this. For example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4291 @code{count-lines-region} moves point. To prevent the user from being
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4292 bothered by jumps that are both unexpected and (from the user's point of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4293 view) unnecessary, @code{save-excursion} is often used to keep point and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4294 mark in the location expected by the user. The use of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4295 @code{save-excursion} is good housekeeping.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4296
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4297 To make sure the house stays clean, @code{save-excursion} restores the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4298 values of point and mark even if something goes wrong in the code inside
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4299 of it (or, to be more precise and to use the proper jargon, ``in case of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4300 abnormal exit''). This feature is very helpful.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4301
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4302 In addition to recording the values of point and mark,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4303 @code{save-excursion} keeps track of the current buffer, and restores
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4304 it, too. This means you can write code that will change the buffer and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4305 have @code{save-excursion} switch you back to the original buffer. This
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4306 is how @code{save-excursion} is used in @code{append-to-buffer}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4307 (@xref{append-to-buffer, , The Definition of @code{append-to-buffer}}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4308
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4309 @node Template for save-excursion, , Point and mark, save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4310 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4311 @subsection Template for a @code{save-excursion} Expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4312
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4313 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4314 The template for code using @code{save-excursion} is simple:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4315
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4316 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4317 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4318 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4319 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4320 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4321 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4322
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4323 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4324 The body of the function is one or more expressions that will be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4325 evaluated in sequence by the Lisp interpreter. If there is more than
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4326 one expression in the body, the value of the last one will be returned
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4327 as the value of the @code{save-excursion} function. The other
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4328 expressions in the body are evaluated only for their side effects; and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4329 @code{save-excursion} itself is used only for its side effect (which
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4330 is restoring the positions of point and mark).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4331
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4332 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4333 In more detail, the template for a @code{save-excursion} expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4334 looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4335
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4336 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4337 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4338 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4339 @var{first-expression-in-body}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4340 @var{second-expression-in-body}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4341 @var{third-expression-in-body}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4342 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4343 @var{last-expression-in-body})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4344 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4345 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4346
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4347 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4348 An expression, of course, may be a symbol on its own or a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4349
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4350 In Emacs Lisp code, a @code{save-excursion} expression often occurs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4351 within the body of a @code{let} expression. It looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4352
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4353 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4354 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4355 (let @var{varlist}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4356 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4357 @var{body}@dots{}))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4358 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4359 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4360
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4361 @node Review, defun Exercises, save-excursion, Writing Defuns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4362 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4363 @section Review
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4364
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4365 In the last few chapters we have introduced a fair number of functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4366 and special forms. Here they are described in brief, along with a few
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4367 similar functions that have not been mentioned yet.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4368
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4369 @table @code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4370 @item eval-last-sexp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4371 Evaluate the last symbolic expression before the current location of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4372 point. The value is printed in the echo area unless the function is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4373 invoked with an argument; in that case, the output is printed in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4374 current buffer. This command is normally bound to @kbd{C-x C-e}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4375
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4376 @item defun
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4377 Define function. This special form has up to five parts: the name,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4378 a template for the arguments that will be passed to the function,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4379 documentation, an optional interactive declaration, and the body of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4380 definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4381
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4382 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4383 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4384
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4385 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4386 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4387 (defun back-to-indentation ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4388 "Move point to first visible character on line."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4389 (interactive)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4390 (beginning-of-line 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4391 (skip-chars-forward " \t"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4392 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4393 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4394
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4395 @item interactive
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4396 Declare to the interpreter that the function can be used
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4397 interactively. This special form may be followed by a string with one
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4398 or more parts that pass the information to the arguments of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4399 function, in sequence. These parts may also tell the interpreter to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4400 prompt for information. Parts of the string are separated by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4401 newlines, @samp{\n}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4402
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4403 Common code characters are:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4404
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4405 @table @code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4406 @item b
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4407 The name of an existing buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4408
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4409 @item f
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4410 The name of an existing file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4411
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4412 @item p
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4413 The numeric prefix argument. (Note that this `p' is lower case.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4414
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4415 @item r
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4416 Point and the mark, as two numeric arguments, smallest first. This
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4417 is the only code letter that specifies two successive arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4418 rather than one.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4419 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4420
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4421 @xref{Interactive Codes, , Code Characters for @samp{interactive},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4422 elisp, The GNU Emacs Lisp Reference Manual}, for a complete list of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4423 code characters.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4424
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4425 @item let
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4426 Declare that a list of variables is for use within the body of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4427 @code{let} and give them an initial value, either @code{nil} or a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4428 specified value; then evaluate the rest of the expressions in the body
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4429 of the @code{let} and return the value of the last one. Inside the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4430 body of the @code{let}, the Lisp interpreter does not see the values of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4431 the variables of the same names that are bound outside of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4432 @code{let}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4433
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4434 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4435 For example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4436
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4437 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4438 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4439 (let ((foo (buffer-name))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4440 (bar (buffer-size)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4441 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4442 "This buffer is %s and has %d characters."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4443 foo bar))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4444 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4445 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4446
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4447 @item save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4448 Record the values of point and mark and the current buffer before
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4449 evaluating the body of this special form. Restore the values of point
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4450 and mark and buffer afterward.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4451
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4452 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4453 For example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4454
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4455 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4456 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4457 (message "We are %d characters into this buffer."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4458 (- (point)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4459 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4460 (goto-char (point-min)) (point))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4461 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4462 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4463
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4464 @item if
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4465 Evaluate the first argument to the function; if it is true, evaluate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4466 the second argument; else evaluate the third argument, if there is one.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4467
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4468 The @code{if} special form is called a @dfn{conditional}. There are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4469 other conditionals in Emacs Lisp, but @code{if} is perhaps the most
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4470 commonly used.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4471
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4472 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4473 For example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4474
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4475 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4476 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4477 (if (string-equal
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4478 (number-to-string 21)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4479 (substring (emacs-version) 10 12))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4480 (message "This is version 21 Emacs")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4481 (message "This is not version 21 Emacs"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4482 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4483 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4484
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4485 @item equal
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4486 @itemx eq
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4487 Test whether two objects are the same. @code{equal} uses one meaning
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4488 of the word `same' and @code{eq} uses another: @code{equal} returns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4489 true if the two objects have a similar structure and contents, such as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4490 two copies of the same book. On the other hand, @code{eq}, returns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4491 true if both arguments are actually the same object.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4492 @findex equal
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4493 @findex eq
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4494
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4495 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4496 @item <
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4497 @itemx >
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4498 @itemx <=
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4499 @itemx >=
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4500 The @code{<} function tests whether its first argument is smaller than
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4501 its second argument. A corresponding function, @code{>}, tests whether
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4502 the first argument is greater than the second. Likewise, @code{<=}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4503 tests whether the first argument is less than or equal to the second and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4504 @code{>=} tests whether the first argument is greater than or equal to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4505 the second. In all cases, both arguments must be numbers or markers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4506 (markers indicate positions in buffers).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4507
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4508 @item string<
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4509 @itemx string-lessp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4510 @itemx string=
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4511 @itemx string-equal
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4512 The @code{string-lessp} function tests whether its first argument is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4513 smaller than the second argument. A shorter, alternative name for the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4514 same function (a @code{defalias}) is @code{string<}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4515
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4516 The arguments to @code{string-lessp} must be strings or symbols; the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4517 ordering is lexicographic, so case is significant. The print names of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4518 symbols are used instead of the symbols themselves.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4519
42109
24f8e84cb04d Indexed `empty string' definition.
Robert J. Chassell <bob@rattlesnake.com>
parents: 42108
diff changeset
4520 @cindex @samp{empty string} defined
42108
dcab51f5352e Define `empty string' a second time, in a slightly more visible location.
Robert J. Chassell <bob@rattlesnake.com>
parents: 41872
diff changeset
4521 An empty string, @samp{""}, a string with no characters in it, is
dcab51f5352e Define `empty string' a second time, in a slightly more visible location.
Robert J. Chassell <bob@rattlesnake.com>
parents: 41872
diff changeset
4522 smaller than any string of characters.
dcab51f5352e Define `empty string' a second time, in a slightly more visible location.
Robert J. Chassell <bob@rattlesnake.com>
parents: 41872
diff changeset
4523
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4524 @code{string-equal} provides the corresponding test for equality. Its
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4525 shorter, alternative name is @code{string=}. There are no string test
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4526 functions that correspond to @var{>}, @code{>=}, or @code{<=}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4527
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4528 @item message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4529 Print a message in the echo area. The first argument is a string that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4530 can contain @samp{%s}, @samp{%d}, or @samp{%c} to print the value of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4531 arguments that follow the string. The argument used by @samp{%s} must
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4532 be a string or a symbol; the argument used by @samp{%d} must be a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4533 number. The argument used by @samp{%c} must be an ascii code number;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4534 it will be printed as the character with that @sc{ascii} code.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4535
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4536 @item setq
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4537 @itemx set
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4538 The @code{setq} function sets the value of its first argument to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4539 value of the second argument. The first argument is automatically
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4540 quoted by @code{setq}. It does the same for succeeding pairs of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4541 arguments. Another function, @code{set}, takes only two arguments and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4542 evaluates both of them before setting the value returned by its first
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4543 argument to the value returned by its second argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4544
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4545 @item buffer-name
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4546 Without an argument, return the name of the buffer, as a string.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4547
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4548 @itemx buffer-file-name
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4549 Without an argument, return the name of the file the buffer is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4550 visiting.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4551
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4552 @item current-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4553 Return the buffer in which Emacs is active; it may not be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4554 the buffer that is visible on the screen.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4555
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4556 @item other-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4557 Return the most recently selected buffer (other than the buffer passed
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4558 to @code{other-buffer} as an argument and other than the current
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4559 buffer).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4560
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4561 @item switch-to-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4562 Select a buffer for Emacs to be active in and display it in the current
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4563 window so users can look at it. Usually bound to @kbd{C-x b}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4564
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4565 @item set-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4566 Switch Emacs' attention to a buffer on which programs will run. Don't
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4567 alter what the window is showing.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4568
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4569 @item buffer-size
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4570 Return the number of characters in the current buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4571
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4572 @item point
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4573 Return the value of the current position of the cursor, as an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4574 integer counting the number of characters from the beginning of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4575 buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4576
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4577 @item point-min
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4578 Return the minimum permissible value of point in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4579 the current buffer. This is 1, unless narrowing is in effect.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4580
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4581 @item point-max
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4582 Return the value of the maximum permissible value of point in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4583 current buffer. This is the end of the buffer, unless narrowing is in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4584 effect.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4585 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4586
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4587 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4588 @node defun Exercises, , Review, Writing Defuns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4589 @section Exercises
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4590
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4591 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4592 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4593 Write a non-interactive function that doubles the value of its
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4594 argument, a number. Make that function interactive.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4595
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4596 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4597 Write a function that tests whether the current value of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4598 @code{fill-column} is greater than the argument passed to the function,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4599 and if so, prints an appropriate message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4600 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4601
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4602 @node Buffer Walk Through, More Complex, Writing Defuns, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4603 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4604 @chapter A Few Buffer--Related Functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4605
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4606 In this chapter we study in detail several of the functions used in GNU
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4607 Emacs. This is called a ``walk-through''. These functions are used as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4608 examples of Lisp code, but are not imaginary examples; with the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4609 exception of the first, simplified function definition, these functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4610 show the actual code used in GNU Emacs. You can learn a great deal from
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4611 these definitions. The functions described here are all related to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4612 buffers. Later, we will study other functions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4613
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4614 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4615 * Finding More:: How to find more information.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4616 * simplified-beginning-of-buffer:: Shows @code{goto-char},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4617 @code{point-min}, and @code{push-mark}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4618 * mark-whole-buffer:: Almost the same as @code{beginning-of-buffer}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4619 * append-to-buffer:: Uses @code{save-excursion} and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4620 @code{insert-buffer-substring}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4621 * Buffer Related Review:: Review.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4622 * Buffer Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4623 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4624
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4625 @node Finding More, simplified-beginning-of-buffer, Buffer Walk Through, Buffer Walk Through
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4626 @section Finding More Information
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4627
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4628 @findex describe-function, @r{introduced}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4629 @cindex Find function documentation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4630 In this walk-through, I will describe each new function as we come to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4631 it, sometimes in detail and sometimes briefly. If you are interested,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4632 you can get the full documentation of any Emacs Lisp function at any
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4633 time by typing @kbd{C-h f} and then the name of the function (and then
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4634 @key{RET}). Similarly, you can get the full documentation for a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4635 variable by typing @kbd{C-h v} and then the name of the variable (and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4636 then @key{RET}).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4637
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4638 @cindex Find source of function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4639 In versions 20 and higher, when a function is written in Emacs Lisp,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4640 @code{describe-function} will also tell you the location of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4641 function definition. If you move point over the file name and press
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4642 the @key{RET} key, which is this case means @code{help-follow} rather
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4643 than `return' or `enter', Emacs will take you directly to the function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4644 definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4645
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4646 More generally, if you want to see a function in its original source
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4647 file, you can use the @code{find-tags} function to jump to it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4648 @code{find-tags} works with a wide variety of languages, not just
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4649 Lisp, and C, and it works with non-programming text as well. For
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4650 example, @code{find-tags} will jump to the various nodes in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4651 Texinfo source file of this document.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4652
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4653 The @code{find-tags} function depends on `tags tables' that record
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4654 the locations of the functions, variables, and other items to which
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4655 @code{find-tags} jumps.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4656
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4657 To use the @code{find-tags} command, type @kbd{M-.} (i.e., type the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4658 @key{META} key and the period key at the same time, or else type the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4659 @key{ESC} key and then type the period key), and then, at the prompt,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4660 type in the name of the function whose source code you want to see,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4661 such as @code{mark-whole-buffer}, and then type @key{RET}. Emacs will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4662 switch buffers and display the source code for the function on your
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4663 screen. To switch back to your current buffer, type @kbd{C-x b
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4664 @key{RET}}. (On some keyboards, the @key{META} key is labelled
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4665 @key{ALT}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4666
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4667 @c !!! 21.0.100 tags table location in this paragraph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4668 @cindex TAGS table, specifying
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4669 @findex find-tags
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4670 Depending on how the initial default values of your copy of Emacs are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4671 set, you may also need to specify the location of your `tags table',
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4672 which is a file called @file{TAGS}. For example, if you are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4673 interested in Emacs sources, the tags table you will most likely want,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4674 if it has already been created for you, will be in a subdirectory of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4675 the @file{/usr/local/share/emacs/} directory; thus you would use the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4676 @code{M-x visit-tags-table} command and specify a pathname such as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4677 @file{/usr/local/share/emacs/21.0.100/lisp/TAGS} or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4678 @file{/usr/local/src/emacs/lisp/TAGS}. If the tags table has
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4679 not already been created, you will have to create it yourself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4680
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4681 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4682 To create a @file{TAGS} file in a specific directory, switch to that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4683 directory in Emacs using @kbd{M-x cd} command, or list the directory
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4684 with @kbd{C-x d} (@code{dired}). Then run the compile command, with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4685 @w{@code{etags *.el}} as the command to execute
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4686
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4687 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4688 M-x compile RET etags *.el RET
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4689 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4690
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4691 For more information, see @ref{etags, , Create Your Own @file{TAGS} File}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4692
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4693 After you become more familiar with Emacs Lisp, you will find that you will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4694 frequently use @code{find-tags} to navigate your way around source code;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4695 and you will create your own @file{TAGS} tables.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4696
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4697 @cindex Library, as term for `file'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4698 Incidentally, the files that contain Lisp code are conventionally
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4699 called @dfn{libraries}. The metaphor is derived from that of a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4700 specialized library, such as a law library or an engineering library,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4701 rather than a general library. Each library, or file, contains
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4702 functions that relate to a particular topic or activity, such as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4703 @file{abbrev.el} for handling abbreviations and other typing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4704 shortcuts, and @file{help.el} for on-line help. (Sometimes several
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4705 libraries provide code for a single activity, as the various
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4706 @file{rmail@dots{}} files provide code for reading electronic mail.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4707 In @cite{The GNU Emacs Manual}, you will see sentences such as ``The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4708 @kbd{C-h p} command lets you search the standard Emacs Lisp libraries
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4709 by topic keywords.''
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4710
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4711 @node simplified-beginning-of-buffer, mark-whole-buffer, Finding More, Buffer Walk Through
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4712 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4713 @section A Simplified @code{beginning-of-buffer} Definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4714 @findex simplified-beginning-of-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4715
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4716 The @code{beginning-of-buffer} command is a good function to start with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4717 since you are likely to be familiar with it and it is easy to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4718 understand. Used as an interactive command, @code{beginning-of-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4719 moves the cursor to the beginning of the buffer, leaving the mark at the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4720 previous position. It is generally bound to @kbd{M-<}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4721
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4722 In this section, we will discuss a shortened version of the function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4723 that shows how it is most frequently used. This shortened function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4724 works as written, but it does not contain the code for a complex option.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4725 In another section, we will describe the entire function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4726 (@xref{beginning-of-buffer, , Complete Definition of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4727 @code{beginning-of-buffer}}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4728
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4729 Before looking at the code, let's consider what the function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4730 definition has to contain: it must include an expression that makes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4731 the function interactive so it can be called by typing @kbd{M-x
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4732 beginning-of-buffer} or by typing a keychord such as @kbd{C-<}; it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4733 must include code to leave a mark at the original position in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4734 buffer; and it must include code to move the cursor to the beginning
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4735 of the buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4736
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4737 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4738 Here is the complete text of the shortened version of the function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4739
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4740 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4741 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4742 (defun simplified-beginning-of-buffer ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4743 "Move point to the beginning of the buffer;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4744 leave mark at previous position."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4745 (interactive)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4746 (push-mark)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4747 (goto-char (point-min)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4748 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4749 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4750
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4751 Like all function definitions, this definition has five parts following
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4752 the special form @code{defun}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4753
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4754 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4755 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4756 The name: in this example, @code{simplified-beginning-of-buffer}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4757
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4758 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4759 A list of the arguments: in this example, an empty list, @code{()},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4760
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4761 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4762 The documentation string.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4763
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4764 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4765 The interactive expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4766
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4767 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4768 The body.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4769 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4770
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4771 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4772 In this function definition, the argument list is empty; this means that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4773 this function does not require any arguments. (When we look at the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4774 definition for the complete function, we will see that it may be passed
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4775 an optional argument.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4776
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4777 The interactive expression tells Emacs that the function is intended to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4778 be used interactively. In this example, @code{interactive} does not have
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4779 an argument because @code{simplified-beginning-of-buffer} does not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4780 require one.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4781
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4782 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4783 The body of the function consists of the two lines:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4784
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4785 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4786 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4787 (push-mark)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4788 (goto-char (point-min))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4789 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4790 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4791
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4792 The first of these lines is the expression, @code{(push-mark)}. When
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4793 this expression is evaluated by the Lisp interpreter, it sets a mark at
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4794 the current position of the cursor, wherever that may be. The position
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4795 of this mark is saved in the mark ring.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4796
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4797 The next line is @code{(goto-char (point-min))}. This expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4798 jumps the cursor to the minimum point in the buffer, that is, to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4799 beginning of the buffer (or to the beginning of the accessible portion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4800 of the buffer if it is narrowed. @xref{Narrowing & Widening, ,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4801 Narrowing and Widening}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4802
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4803 The @code{push-mark} command sets a mark at the place where the cursor
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4804 was located before it was moved to the beginning of the buffer by the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4805 @code{(goto-char (point-min))} expression. Consequently, you can, if
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4806 you wish, go back to where you were originally by typing @kbd{C-x C-x}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4807
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4808 That is all there is to the function definition!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4809
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4810 @findex describe-function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4811 When you are reading code such as this and come upon an unfamiliar
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4812 function, such as @code{goto-char}, you can find out what it does by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4813 using the @code{describe-function} command. To use this command, type
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4814 @kbd{C-h f} and then type in the name of the function and press
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4815 @key{RET}. The @code{describe-function} command will print the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4816 function's documentation string in a @file{*Help*} window. For
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4817 example, the documentation for @code{goto-char} is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4818
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4819 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4820 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4821 One arg, a number. Set point to that number.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4822 Beginning of buffer is position (point-min),
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4823 end is (point-max).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4824 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4825 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4826
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4827 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4828 (The prompt for @code{describe-function} will offer you the symbol
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4829 under or preceding the cursor, so you can save typing by positioning
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4830 the cursor right over or after the function and then typing @kbd{C-h f
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4831 @key{RET}}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4832
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4833 The @code{end-of-buffer} function definition is written in the same way as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4834 the @code{beginning-of-buffer} definition except that the body of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4835 function contains the expression @code{(goto-char (point-max))} in place
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4836 of @code{(goto-char (point-min))}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4837
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4838 @node mark-whole-buffer, append-to-buffer, simplified-beginning-of-buffer, Buffer Walk Through
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4839 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4840 @section The Definition of @code{mark-whole-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4841 @findex mark-whole-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4842
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4843 The @code{mark-whole-buffer} function is no harder to understand than the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4844 @code{simplified-beginning-of-buffer} function. In this case, however,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4845 we will look at the complete function, not a shortened version.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4846
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4847 The @code{mark-whole-buffer} function is not as commonly used as the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4848 @code{beginning-of-buffer} function, but is useful nonetheless: it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4849 marks a whole buffer as a region by putting point at the beginning and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4850 a mark at the end of the buffer. It is generally bound to @kbd{C-x
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4851 h}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4852
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4853
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4854 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4855 * mark-whole-buffer overview::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4856 * Body of mark-whole-buffer:: Only three lines of code.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4857 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4858
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4859
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4860 @node mark-whole-buffer overview, Body of mark-whole-buffer, mark-whole-buffer, mark-whole-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4861 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4862 @unnumberedsubsec An overview of @code{mark-whole-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4863 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4864
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4865 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4866 In GNU Emacs 20, the code for the complete function looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4867
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4868 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4869 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4870 (defun mark-whole-buffer ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4871 "Put point at beginning and mark at end of buffer."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4872 (interactive)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4873 (push-mark (point))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4874 (push-mark (point-max))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4875 (goto-char (point-min)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4876 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4877 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4878
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4879 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4880 Like all other functions, the @code{mark-whole-buffer} function fits
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4881 into the template for a function definition. The template looks like
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4882 this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4883
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4884 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4885 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4886 (defun @var{name-of-function} (@var{argument-list})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4887 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4888 (@var{interactive-expression}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4889 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4890 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4891 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4892
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4893 Here is how the function works: the name of the function is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4894 @code{mark-whole-buffer}; it is followed by an empty argument list,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4895 @samp{()}, which means that the function does not require arguments.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4896 The documentation comes next.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4897
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4898 The next line is an @code{(interactive)} expression that tells Emacs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4899 that the function will be used interactively. These details are similar
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4900 to the @code{simplified-beginning-of-buffer} function described in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4901 previous section.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4902
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4903 @node Body of mark-whole-buffer, , mark-whole-buffer overview, mark-whole-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4904 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4905 @subsection Body of @code{mark-whole-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4906
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4907 The body of the @code{mark-whole-buffer} function consists of three
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4908 lines of code:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4909
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4910 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4911 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4912 (push-mark (point))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4913 (push-mark (point-max))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4914 (goto-char (point-min))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4915 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4916 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4917
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4918 The first of these lines is the expression, @code{(push-mark (point))}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4919
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4920 This line does exactly the same job as the first line of the body of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4921 the @code{simplified-beginning-of-buffer} function, which is written
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4922 @code{(push-mark)}. In both cases, the Lisp interpreter sets a mark
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4923 at the current position of the cursor.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4924
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4925 I don't know why the expression in @code{mark-whole-buffer} is written
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4926 @code{(push-mark (point))} and the expression in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4927 @code{beginning-of-buffer} is written @code{(push-mark)}. Perhaps
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4928 whoever wrote the code did not know that the arguments for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4929 @code{push-mark} are optional and that if @code{push-mark} is not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4930 passed an argument, the function automatically sets mark at the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4931 location of point by default. Or perhaps the expression was written
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4932 so as to parallel the structure of the next line. In any case, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4933 line causes Emacs to determine the position of point and set a mark
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4934 there.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4935
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4936 The next line of @code{mark-whole-buffer} is @code{(push-mark (point-max)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4937 This expression sets a mark at the point in the buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4938 that has the highest number. This will be the end of the buffer (or,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4939 if the buffer is narrowed, the end of the accessible portion of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4940 buffer. @xref{Narrowing & Widening, , Narrowing and Widening}, for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4941 more about narrowing.) After this mark has been set, the previous
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4942 mark, the one set at point, is no longer set, but Emacs remembers its
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4943 position, just as all other recent marks are always remembered. This
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4944 means that you can, if you wish, go back to that position by typing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4945 @kbd{C-u C-@key{SPC}} twice.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4946
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4947 (In GNU Emacs 21, the @code{(push-mark (point-max)} is slightly more
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4948 complicated than shown here. The line reads
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4949
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4950 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4951 (push-mark (point-max) nil t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4952 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4953
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4954 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4955 (The expression works nearly the same as before. It sets a mark at
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4956 the highest numbered place in the buffer that it can. However, in
41872
2a4f1d831675 Fixed typographic error.
Robert J. Chassell <bob@rattlesnake.com>
parents: 41674
diff changeset
4957 this version, @code{push-mark} has two additional arguments. The
2a4f1d831675 Fixed typographic error.
Robert J. Chassell <bob@rattlesnake.com>
parents: 41674
diff changeset
4958 second argument to @code{push-mark} is @code{nil}. This tells the
2a4f1d831675 Fixed typographic error.
Robert J. Chassell <bob@rattlesnake.com>
parents: 41674
diff changeset
4959 function it @emph{should} display a message that says `Mark set' when
2a4f1d831675 Fixed typographic error.
Robert J. Chassell <bob@rattlesnake.com>
parents: 41674
diff changeset
4960 it pushes the mark. The third argument is @code{t}. This tells
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4961 @code{push-mark} to activate the mark when Transient Mark mode is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4962 turned on. Transient Mark mode highlights the currently active
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4963 region. It is usually turned off.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4964
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4965 Finally, the last line of the function is @code{(goto-char
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4966 (point-min)))}. This is written exactly the same way as it is written
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4967 in @code{beginning-of-buffer}. The expression moves the cursor to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4968 the minimum point in the buffer, that is, to the beginning of the buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4969 (or to the beginning of the accessible portion of the buffer). As a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4970 result of this, point is placed at the beginning of the buffer and mark
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4971 is set at the end of the buffer. The whole buffer is, therefore, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4972 region.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4973
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4974 @node append-to-buffer, Buffer Related Review, mark-whole-buffer, Buffer Walk Through
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4975 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4976 @section The Definition of @code{append-to-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4977 @findex append-to-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4978
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4979 The @code{append-to-buffer} command is very nearly as simple as the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4980 @code{mark-whole-buffer} command. What it does is copy the region (that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4981 is, the part of the buffer between point and mark) from the current
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4982 buffer to a specified buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4983
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4984 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4985 * append-to-buffer overview::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4986 * append interactive:: A two part interactive expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4987 * append-to-buffer body:: Incorporates a @code{let} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4988 * append save-excursion:: How the @code{save-excursion} works.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4989 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4990
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4991 @node append-to-buffer overview, append interactive, append-to-buffer, append-to-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4992 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4993 @unnumberedsubsec An Overview of @code{append-to-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4994 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4995
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4996 @findex insert-buffer-substring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4997 The @code{append-to-buffer} command uses the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4998 @code{insert-buffer-substring} function to copy the region.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4999 @code{insert-buffer-substring} is described by its name: it takes a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5000 string of characters from part of a buffer, a ``substring'', and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5001 inserts them into another buffer. Most of @code{append-to-buffer} is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5002 concerned with setting up the conditions for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5003 @code{insert-buffer-substring} to work: the code must specify both the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5004 buffer to which the text will go and the region that will be copied.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5005 Here is the complete text of the function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5006
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5007 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5008 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5009 (defun append-to-buffer (buffer start end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5010 "Append to specified buffer the text of the region.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5011 It is inserted into that buffer before its point.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5012 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5013
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5014 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5015 When calling from a program, give three arguments:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5016 a buffer or the name of one, and two character numbers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5017 specifying the portion of the current buffer to be copied."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5018 (interactive "BAppend to buffer:@: \nr")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5019 (let ((oldbuf (current-buffer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5020 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5021 (set-buffer (get-buffer-create buffer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5022 (insert-buffer-substring oldbuf start end))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5023 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5024 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5025
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5026 The function can be understood by looking at it as a series of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5027 filled-in templates.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5028
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5029 The outermost template is for the function definition. In this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5030 function, it looks like this (with several slots filled in):
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5031
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5032 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5033 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5034 (defun append-to-buffer (buffer start end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5035 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5036 (interactive "BAppend to buffer:@: \nr")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5037 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5038 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5039 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5040
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5041 The first line of the function includes its name and three arguments.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5042 The arguments are the @code{buffer} to which the text will be copied, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5043 the @code{start} and @code{end} of the region in the current buffer that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5044 will be copied.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5045
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5046 The next part of the function is the documentation, which is clear and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5047 complete.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5048
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5049 @node append interactive, append-to-buffer body, append-to-buffer overview, append-to-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5050 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5051 @subsection The @code{append-to-buffer} Interactive Expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5052
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5053 Since the @code{append-to-buffer} function will be used interactively,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5054 the function must have an @code{interactive} expression. (For a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5055 review of @code{interactive}, see @ref{Interactive, , Making a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5056 Function Interactive}.) The expression reads as follows:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5057
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5058 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5059 (interactive "BAppend to buffer:@: \nr")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5060 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5061
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5062 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5063 This expression has an argument inside of quotation marks and that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5064 argument has two parts, separated by @samp{\n}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5065
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5066 The first part is @samp{BAppend to buffer:@: }. Here, the @samp{B}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5067 tells Emacs to ask for the name of the buffer that will be passed to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5068 function. Emacs will ask for the name by prompting the user in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5069 minibuffer, using the string following the @samp{B}, which is the string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5070 @samp{Append to buffer:@: }. Emacs then binds the variable @code{buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5071 in the function's argument list to the specified buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5072
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5073 The newline, @samp{\n}, separates the first part of the argument from
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5074 the second part. It is followed by an @samp{r} that tells Emacs to bind
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5075 the two arguments that follow the symbol @code{buffer} in the function's
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5076 argument list (that is, @code{start} and @code{end}) to the values of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5077 point and mark.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5078
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5079 @node append-to-buffer body, append save-excursion, append interactive, append-to-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5080 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5081 @subsection The Body of @code{append-to-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5082
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5083 The body of the @code{append-to-buffer} function begins with @code{let}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5084
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5085 As we have seen before (@pxref{let, , @code{let}}), the purpose of a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5086 @code{let} expression is to create and give initial values to one or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5087 more variables that will only be used within the body of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5088 @code{let}. This means that such a variable will not be confused with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5089 any variable of the same name outside the @code{let} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5090
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5091 We can see how the @code{let} expression fits into the function as a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5092 whole by showing a template for @code{append-to-buffer} with the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5093 @code{let} expression in outline:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5094
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5095 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5096 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5097 (defun append-to-buffer (buffer start end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5098 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5099 (interactive "BAppend to buffer:@: \nr")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5100 (let ((@var{variable} @var{value}))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5101 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5102 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5103 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5104
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5105 The @code{let} expression has three elements:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5106
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5107 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5108 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5109 The symbol @code{let};
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5110
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5111 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5112 A varlist containing, in this case, a single two-element list,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5113 @code{(@var{variable} @var{value})};
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5114
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5115 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5116 The body of the @code{let} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5117 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5118
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5119 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5120 In the @code{append-to-buffer} function, the varlist looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5121
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5122 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5123 (oldbuf (current-buffer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5124 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5125
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5126 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5127 In this part of the @code{let} expression, the one variable,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5128 @code{oldbuf}, is bound to the value returned by the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5129 @code{(current-buffer)} expression. The variable, @code{oldbuf}, is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5130 used to keep track of the buffer in which you are working and from
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5131 which you will copy.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5132
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5133 The element or elements of a varlist are surrounded by a set of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5134 parentheses so the Lisp interpreter can distinguish the varlist from
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5135 the body of the @code{let}. As a consequence, the two-element list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5136 within the varlist is surrounded by a circumscribing set of parentheses.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5137 The line looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5138
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5139 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5140 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5141 (let ((oldbuf (current-buffer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5142 @dots{} )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5143 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5144 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5145
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5146 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5147 The two parentheses before @code{oldbuf} might surprise you if you did
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5148 not realize that the first parenthesis before @code{oldbuf} marks the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5149 boundary of the varlist and the second parenthesis marks the beginning
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5150 of the two-element list, @code{(oldbuf (current-buffer))}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5151
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5152 @node append save-excursion, , append-to-buffer body, append-to-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5153 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5154 @subsection @code{save-excursion} in @code{append-to-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5155
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5156 The body of the @code{let} expression in @code{append-to-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5157 consists of a @code{save-excursion} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5158
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5159 The @code{save-excursion} function saves the locations of point and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5160 mark, and restores them to those positions after the expressions in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5161 body of the @code{save-excursion} complete execution. In addition,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5162 @code{save-excursion} keeps track of the original buffer, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5163 restores it. This is how @code{save-excursion} is used in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5164 @code{append-to-buffer}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5165
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5166 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5167 @cindex Indentation for formatting
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5168 @cindex Formatting convention
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5169 Incidentally, it is worth noting here that a Lisp function is normally
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5170 formatted so that everything that is enclosed in a multi-line spread is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5171 indented more to the right than the first symbol. In this function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5172 definition, the @code{let} is indented more than the @code{defun}, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5173 the @code{save-excursion} is indented more than the @code{let}, like
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5174 this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5175
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5176 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5177 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5178 (defun @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5179 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5180 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5181 (let@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5182 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5183 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5184 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5185 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5186
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5187 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5188 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5189 This formatting convention makes it easy to see that the two lines in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5190 the body of the @code{save-excursion} are enclosed by the parentheses
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5191 associated with @code{save-excursion}, just as the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5192 @code{save-excursion} itself is enclosed by the parentheses associated
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5193 with the @code{let}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5194
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5195 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5196 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5197 (let ((oldbuf (current-buffer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5198 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5199 (set-buffer (get-buffer-create buffer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5200 (insert-buffer-substring oldbuf start end))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5201 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5202 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5203
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5204 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5205 The use of the @code{save-excursion} function can be viewed as a process
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5206 of filling in the slots of a template:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5207
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5208 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5209 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5210 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5211 @var{first-expression-in-body}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5212 @var{second-expression-in-body}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5213 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5214 @var{last-expression-in-body})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5215 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5216 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5217
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5218 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5219 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5220 In this function, the body of the @code{save-excursion} contains only
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5221 two expressions. The body looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5222
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5223 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5224 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5225 (set-buffer (get-buffer-create buffer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5226 (insert-buffer-substring oldbuf start end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5227 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5228 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5229
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5230 When the @code{append-to-buffer} function is evaluated, the two
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5231 expressions in the body of the @code{save-excursion} are evaluated in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5232 sequence. The value of the last expression is returned as the value of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5233 the @code{save-excursion} function; the other expression is evaluated
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5234 only for its side effects.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5235
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5236 The first line in the body of the @code{save-excursion} uses the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5237 @code{set-buffer} function to change the current buffer to the one
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5238 specified in the first argument to @code{append-to-buffer}. (Changing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5239 the buffer is the side effect; as we have said before, in Lisp, a side
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5240 effect is often the primary thing we want.) The second line does the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5241 primary work of the function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5242
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5243 The @code{set-buffer} function changes Emacs' attention to the buffer to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5244 which the text will be copied and from which @code{save-excursion} will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5245 return.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5246
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5247 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5248 The line looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5249
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5250 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5251 (set-buffer (get-buffer-create buffer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5252 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5253
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5254 The innermost expression of this list is @code{(get-buffer-create
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5255 buffer)}. This expression uses the @code{get-buffer-create} function,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5256 which either gets the named buffer, or if it does not exist, creates one
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5257 with the given name. This means you can use @code{append-to-buffer} to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5258 put text into a buffer that did not previously exist.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5259
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5260 @code{get-buffer-create} also keeps @code{set-buffer} from getting an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5261 unnecessary error: @code{set-buffer} needs a buffer to go to; if you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5262 were to specify a buffer that does not exist, Emacs would baulk.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5263 Since @code{get-buffer-create} will create a buffer if none exists,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5264 @code{set-buffer} is always provided with a buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5265
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5266 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5267 The last line of @code{append-to-buffer} does the work of appending
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5268 the text:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5269
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5270 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5271 (insert-buffer-substring oldbuf start end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5272 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5273
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5274 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5275 The @code{insert-buffer-substring} function copies a string @emph{from}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5276 the buffer specified as its first argument and inserts the string into
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5277 the present buffer. In this case, the argument to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5278 @code{insert-buffer-substring} is the value of the variable created and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5279 bound by the @code{let}, namely the value of @code{oldbuf}, which was
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5280 the current buffer when you gave the @code{append-to-buffer} command.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5281
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5282 After @code{insert-buffer-substring} has done its work,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5283 @code{save-excursion} will restore the action to the original buffer and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5284 @code{append-to-buffer} will have done its job.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5285
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5286 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5287 Written in skeletal form, the workings of the body look like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5288
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5289 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5290 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5291 (let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5292 (save-excursion ; @r{Keep track of buffer.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5293 @var{change-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5294 @var{insert-substring-from-}@code{oldbuf}@var{-into-buffer})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5295
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5296 @var{change-back-to-original-buffer-when-finished}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5297 @var{let-the-local-meaning-of-}@code{oldbuf}@var{-disappear-when-finished}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5298
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5299 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5300 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5301
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5302 In summary, @code{append-to-buffer} works as follows: it saves the value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5303 of the current buffer in the variable called @code{oldbuf}. It gets the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5304 new buffer, creating one if need be, and switches Emacs to it. Using
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5305 the value of @code{oldbuf}, it inserts the region of text from the old
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5306 buffer into the new buffer; and then using @code{save-excursion}, it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5307 brings you back to your original buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5308
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5309 In looking at @code{append-to-buffer}, you have explored a fairly
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5310 complex function. It shows how to use @code{let} and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5311 @code{save-excursion}, and how to change to and come back from another
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5312 buffer. Many function definitions use @code{let},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5313 @code{save-excursion}, and @code{set-buffer} this way.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5314
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5315 @node Buffer Related Review, Buffer Exercises, append-to-buffer, Buffer Walk Through
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5316 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5317 @section Review
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5318
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5319 Here is a brief summary of the various functions discussed in this chapter.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5320
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5321 @table @code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5322 @item describe-function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5323 @itemx describe-variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5324 Print the documentation for a function or variable.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5325 Conventionally bound to @kbd{C-h f} and @kbd{C-h v}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5326
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5327 @item find-tag
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5328 Find the file containing the source for a function or variable and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5329 switch buffers to it, positioning point at the beginning of the item.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5330 Conventionally bound to @kbd{M-.} (that's a period following the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5331 @key{META} key).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5332
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5333 @item save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5334 Save the location of point and mark and restore their values after the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5335 arguments to @code{save-excursion} have been evaluated. Also, remember
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5336 the current buffer and return to it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5337
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5338 @item push-mark
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5339 Set mark at a location and record the value of the previous mark on the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5340 mark ring. The mark is a location in the buffer that will keep its
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5341 relative position even if text is added to or removed from the buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5342
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5343 @item goto-char
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5344 Set point to the location specified by the value of the argument, which
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5345 can be a number, a marker, or an expression that returns the number of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5346 a position, such as @code{(point-min)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5347
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5348 @item insert-buffer-substring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5349 Copy a region of text from a buffer that is passed to the function as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5350 an argument and insert the region into the current buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5351
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5352 @item mark-whole-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5353 Mark the whole buffer as a region. Normally bound to @kbd{C-x h}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5354
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5355 @item set-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5356 Switch the attention of Emacs to another buffer, but do not change the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5357 window being displayed. Used when the program rather than a human is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5358 to work on a different buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5359
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5360 @item get-buffer-create
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5361 @itemx get-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5362 Find a named buffer or create one if a buffer of that name does not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5363 exist. The @code{get-buffer} function returns @code{nil} if the named
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5364 buffer does not exist.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5365 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5366
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5367 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5368 @node Buffer Exercises, , Buffer Related Review, Buffer Walk Through
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5369 @section Exercises
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5370
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5371 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5372 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5373 Write your own @code{simplified-end-of-buffer} function definition;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5374 then test it to see whether it works.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5375
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5376 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5377 Use @code{if} and @code{get-buffer} to write a function that prints a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5378 message telling you whether a buffer exists.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5379
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5380 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5381 Using @code{find-tag}, find the source for the @code{copy-to-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5382 function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5383 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5384
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5385 @node More Complex, Narrowing & Widening, Buffer Walk Through, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5386 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5387 @chapter A Few More Complex Functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5388
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5389 In this chapter, we build on what we have learned in previous chapters
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5390 by looking at more complex functions. The @code{copy-to-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5391 function illustrates use of two @code{save-excursion} expressions in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5392 one definition, while the @code{insert-buffer} function illustrates
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5393 use of an asterisk in an @code{interactive} expression, use of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5394 @code{or}, and the important distinction between a name and the object
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5395 to which the name refers.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5396
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5397 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5398 * copy-to-buffer:: With @code{set-buffer}, @code{get-buffer-create}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5399 * insert-buffer:: Read-only, and with @code{or}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5400 * beginning-of-buffer:: Shows @code{goto-char},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5401 @code{point-min}, and @code{push-mark}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5402 * Second Buffer Related Review::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5403 * optional Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5404 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5405
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5406 @node copy-to-buffer, insert-buffer, More Complex, More Complex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5407 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5408 @section The Definition of @code{copy-to-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5409 @findex copy-to-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5410
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5411 After understanding how @code{append-to-buffer} works, it is easy to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5412 understand @code{copy-to-buffer}. This function copies text into a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5413 buffer, but instead of adding to the second buffer, it replaces the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5414 previous text in the second buffer. The code for the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5415 @code{copy-to-buffer} function is almost the same as the code for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5416 @code{append-to-buffer}, except that @code{erase-buffer} and a second
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5417 @code{save-excursion} are used. (@xref{append-to-buffer, , The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5418 Definition of @code{append-to-buffer}}, for the description of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5419 @code{append-to-buffer}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5420
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5421 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5422 The body of @code{copy-to-buffer} looks like this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5423
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5424 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5425 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5426 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5427 (interactive "BCopy to buffer:@: \nr")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5428 (let ((oldbuf (current-buffer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5429 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5430 (set-buffer (get-buffer-create buffer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5431 (erase-buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5432 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5433 (insert-buffer-substring oldbuf start end)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5434 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5435 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5436
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5437 This code is similar to the code in @code{append-to-buffer}: it is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5438 only after changing to the buffer to which the text will be copied
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5439 that the definition for this function diverges from the definition for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5440 @code{append-to-buffer}: the @code{copy-to-buffer} function erases the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5441 buffer's former contents. (This is what is meant by `replacement'; to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5442 replace text, Emacs erases the previous text and then inserts new
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5443 text.) After erasing the previous contents of the buffer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5444 @code{save-excursion} is used for a second time and the new text is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5445 inserted.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5446
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5447 Why is @code{save-excursion} used twice? Consider again what the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5448 function does.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5449
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5450 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5451 In outline, the body of @code{copy-to-buffer} looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5452
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5453 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5454 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5455 (let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5456 (save-excursion ; @r{First use of @code{save-excursion}.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5457 @var{change-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5458 (erase-buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5459 (save-excursion ; @r{Second use of @code{save-excursion}.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5460 @var{insert-substring-from-}@code{oldbuf}@var{-into-buffer})))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5461 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5462 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5463
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5464 The first use of @code{save-excursion} returns Emacs to the buffer from
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5465 which the text is being copied. That is clear, and is just like its use
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5466 in @code{append-to-buffer}. Why the second use? The reason is that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5467 @code{insert-buffer-substring} always leaves point at the @emph{end} of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5468 the region being inserted. The second @code{save-excursion} causes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5469 Emacs to leave point at the beginning of the text being inserted. In
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5470 most circumstances, users prefer to find point at the beginning of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5471 inserted text. (Of course, the @code{copy-to-buffer} function returns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5472 the user to the original buffer when done---but if the user @emph{then}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5473 switches to the copied-to buffer, point will go to the beginning of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5474 text. Thus, this use of a second @code{save-excursion} is a little
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5475 nicety.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5476
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5477 @node insert-buffer, beginning-of-buffer, copy-to-buffer, More Complex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5478 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5479 @section The Definition of @code{insert-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5480 @findex insert-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5481
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5482 @code{insert-buffer} is yet another buffer-related function. This
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5483 command copies another buffer @emph{into} the current buffer. It is the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5484 reverse of @code{append-to-buffer} or @code{copy-to-buffer}, since they
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5485 copy a region of text @emph{from} the current buffer to another buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5486
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5487 In addition, this code illustrates the use of @code{interactive} with a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5488 buffer that might be @dfn{read-only} and the important distinction
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5489 between the name of an object and the object actually referred to.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5490
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5491 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5492 * insert-buffer code::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5493 * insert-buffer interactive:: When you can read, but not write.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5494 * insert-buffer body:: The body has an @code{or} and a @code{let}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5495 * if & or:: Using an @code{if} instead of an @code{or}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5496 * Insert or:: How the @code{or} expression works.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5497 * Insert let:: Two @code{save-excursion} expressions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5498 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5499
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5500 @node insert-buffer code, insert-buffer interactive, insert-buffer, insert-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5501 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5502 @unnumberedsubsec The Code for @code{insert-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5503 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5504
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5505 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5506 Here is the code:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5507
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5508 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5509 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5510 (defun insert-buffer (buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5511 "Insert after point the contents of BUFFER.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5512 Puts mark after the inserted text.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5513 BUFFER may be a buffer or a buffer name."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5514 (interactive "*bInsert buffer:@: ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5515 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5516 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5517 (or (bufferp buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5518 (setq buffer (get-buffer buffer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5519 (let (start end newmark)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5520 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5521 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5522 (set-buffer buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5523 (setq start (point-min) end (point-max)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5524 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5525 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5526 (insert-buffer-substring buffer start end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5527 (setq newmark (point)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5528 (push-mark newmark)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5529 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5530 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5531
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5532 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5533 As with other function definitions, you can use a template to see an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5534 outline of the function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5535
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5536 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5537 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5538 (defun insert-buffer (buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5539 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5540 (interactive "*bInsert buffer:@: ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5541 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5542 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5543 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5544
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5545 @node insert-buffer interactive, insert-buffer body, insert-buffer code, insert-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5546 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5547 @subsection The Interactive Expression in @code{insert-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5548 @findex interactive, @r{example use of}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5549
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5550 In @code{insert-buffer}, the argument to the @code{interactive}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5551 declaration has two parts, an asterisk, @samp{*}, and @samp{bInsert
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5552 buffer:@: }.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5553
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5554 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5555 * Read-only buffer:: When a buffer cannot be modified.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5556 * b for interactive:: An existing buffer or else its name.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5557 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5558
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5559 @node Read-only buffer, b for interactive, insert-buffer interactive, insert-buffer interactive
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5560 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5561 @unnumberedsubsubsec A Read-only Buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5562 @cindex Read-only buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5563 @cindex Asterisk for read-only buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5564 @findex * @r{for read-only buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5565
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5566 The asterisk is for the situation when the buffer is a read-only
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5567 buffer---a buffer that cannot be modified. If @code{insert-buffer} is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5568 called on a buffer that is read-only, a message to this effect is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5569 printed in the echo area and the terminal may beep or blink at you;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5570 you will not be permitted to insert anything into current buffer. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5571 asterisk does not need to be followed by a newline to separate it from
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5572 the next argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5573
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5574 @node b for interactive, , Read-only buffer, insert-buffer interactive
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5575 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5576 @unnumberedsubsubsec @samp{b} in an Interactive Expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5577
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5578 The next argument in the interactive expression starts with a lower
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5579 case @samp{b}. (This is different from the code for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5580 @code{append-to-buffer}, which uses an upper-case @samp{B}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5581 @xref{append-to-buffer, , The Definition of @code{append-to-buffer}}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5582 The lower-case @samp{b} tells the Lisp interpreter that the argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5583 for @code{insert-buffer} should be an existing buffer or else its
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5584 name. (The upper-case @samp{B} option provides for the possibility
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5585 that the buffer does not exist.) Emacs will prompt you for the name
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5586 of the buffer, offering you a default buffer, with name completion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5587 enabled. If the buffer does not exist, you receive a message that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5588 says ``No match''; your terminal may beep at you as well.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5589
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5590 @node insert-buffer body, if & or, insert-buffer interactive, insert-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5591 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5592 @subsection The Body of the @code{insert-buffer} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5593
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5594 The body of the @code{insert-buffer} function has two major parts: an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5595 @code{or} expression and a @code{let} expression. The purpose of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5596 @code{or} expression is to ensure that the argument @code{buffer} is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5597 bound to a buffer and not just the name of a buffer. The body of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5598 @code{let} expression contains the code which copies the other buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5599 into the current buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5600
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5601 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5602 In outline, the two expressions fit into the @code{insert-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5603 function like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5604
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5605 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5606 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5607 (defun insert-buffer (buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5608 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5609 (interactive "*bInsert buffer:@: ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5610 (or @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5611 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5612 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5613 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5614 (let (@var{varlist})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5615 @var{body-of-}@code{let}@dots{} )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5616 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5617 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5618
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5619 To understand how the @code{or} expression ensures that the argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5620 @code{buffer} is bound to a buffer and not to the name of a buffer, it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5621 is first necessary to understand the @code{or} function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5622
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5623 Before doing this, let me rewrite this part of the function using
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5624 @code{if} so that you can see what is done in a manner that will be familiar.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5625
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5626 @node if & or, Insert or, insert-buffer body, insert-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5627 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5628 @subsection @code{insert-buffer} With an @code{if} Instead of an @code{or}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5629
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5630 The job to be done is to make sure the value of @code{buffer} is a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5631 buffer itself and not the name of a buffer. If the value is the name,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5632 then the buffer itself must be got.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5633
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5634 You can imagine yourself at a conference where an usher is wandering
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5635 around holding a list with your name on it and looking for you: the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5636 usher is ``bound'' to your name, not to you; but when the usher finds
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5637 you and takes your arm, the usher becomes ``bound'' to you.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5638
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5639 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5640 In Lisp, you might describe this situation like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5641
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5642 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5643 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5644 (if (not (holding-on-to-guest))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5645 (find-and-take-arm-of-guest))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5646 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5647 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5648
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5649 We want to do the same thing with a buffer---if we do not have the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5650 buffer itself, we want to get it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5651
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5652 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5653 Using a predicate called @code{bufferp} that tells us whether we have a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5654 buffer (rather than its name), we can write the code like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5655
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5656 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5657 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5658 (if (not (bufferp buffer)) ; @r{if-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5659 (setq buffer (get-buffer buffer))) ; @r{then-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5660 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5661 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5662
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5663 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5664 Here, the true-or-false-test of the @code{if} expression is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5665 @w{@code{(not (bufferp buffer))}}; and the then-part is the expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5666 @w{@code{(setq buffer (get-buffer buffer))}}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5667
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5668 In the test, the function @code{bufferp} returns true if its argument is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5669 a buffer---but false if its argument is the name of the buffer. (The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5670 last character of the function name @code{bufferp} is the character
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5671 @samp{p}; as we saw earlier, such use of @samp{p} is a convention that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5672 indicates that the function is a predicate, which is a term that means
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5673 that the function will determine whether some property is true or false.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5674 @xref{Wrong Type of Argument, , Using the Wrong Type Object as an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5675 Argument}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5676
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5677 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5678 The function @code{not} precedes the expression @code{(bufferp buffer)},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5679 so the true-or-false-test looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5680
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5681 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5682 (not (bufferp buffer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5683 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5684
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5685 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5686 @code{not} is a function that returns true if its argument is false
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5687 and false if its argument is true. So if @code{(bufferp buffer)}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5688 returns true, the @code{not} expression returns false and vice-versa:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5689 what is ``not true'' is false and what is ``not false'' is true.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5690
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5691 Using this test, the @code{if} expression works as follows: when the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5692 value of the variable @code{buffer} is actually a buffer rather then
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5693 its name, the true-or-false-test returns false and the @code{if}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5694 expression does not evaluate the then-part. This is fine, since we do
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5695 not need to do anything to the variable @code{buffer} if it really is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5696 a buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5697
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5698 On the other hand, when the value of @code{buffer} is not a buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5699 itself, but the name of a buffer, the true-or-false-test returns true
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5700 and the then-part of the expression is evaluated. In this case, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5701 then-part is @code{(setq buffer (get-buffer buffer))}. This
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5702 expression uses the @code{get-buffer} function to return an actual
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5703 buffer itself, given its name. The @code{setq} then sets the variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5704 @code{buffer} to the value of the buffer itself, replacing its previous
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5705 value (which was the name of the buffer).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5706
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5707 @node Insert or, Insert let, if & or, insert-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5708 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5709 @subsection The @code{or} in the Body
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5710
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5711 The purpose of the @code{or} expression in the @code{insert-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5712 function is to ensure that the argument @code{buffer} is bound to a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5713 buffer and not just to the name of a buffer. The previous section shows
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5714 how the job could have been done using an @code{if} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5715 However, the @code{insert-buffer} function actually uses @code{or}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5716 To understand this, it is necessary to understand how @code{or} works.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5717
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5718 @findex or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5719 An @code{or} function can have any number of arguments. It evaluates
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5720 each argument in turn and returns the value of the first of its
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5721 arguments that is not @code{nil}. Also, and this is a crucial feature
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5722 of @code{or}, it does not evaluate any subsequent arguments after
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5723 returning the first non-@code{nil} value.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5724
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5725 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5726 The @code{or} expression looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5727
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5728 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5729 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5730 (or (bufferp buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5731 (setq buffer (get-buffer buffer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5732 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5733 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5734
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5735 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5736 The first argument to @code{or} is the expression @code{(bufferp buffer)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5737 This expression returns true (a non-@code{nil} value) if the buffer is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5738 actually a buffer, and not just the name of a buffer. In the @code{or}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5739 expression, if this is the case, the @code{or} expression returns this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5740 true value and does not evaluate the next expression---and this is fine
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5741 with us, since we do not want to do anything to the value of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5742 @code{buffer} if it really is a buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5743
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5744 On the other hand, if the value of @code{(bufferp buffer)} is @code{nil},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5745 which it will be if the value of @code{buffer} is the name of a buffer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5746 the Lisp interpreter evaluates the next element of the @code{or}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5747 expression. This is the expression @code{(setq buffer (get-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5748 buffer))}. This expression returns a non-@code{nil} value, which
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5749 is the value to which it sets the variable @code{buffer}---and this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5750 value is a buffer itself, not the name of a buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5751
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5752 The result of all this is that the symbol @code{buffer} is always
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5753 bound to a buffer itself rather than to the name of a buffer. All
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5754 this is necessary because the @code{set-buffer} function in a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5755 following line only works with a buffer itself, not with the name to a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5756 buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5757
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5758 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5759 Incidentally, using @code{or}, the situation with the usher would be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5760 written like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5761
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5762 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5763 (or (holding-on-to-guest) (find-and-take-arm-of-guest))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5764 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5765
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5766 @node Insert let, , Insert or, insert-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5767 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5768 @subsection The @code{let} Expression in @code{insert-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5769
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5770 After ensuring that the variable @code{buffer} refers to a buffer itself
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5771 and not just to the name of a buffer, the @code{insert-buffer function}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5772 continues with a @code{let} expression. This specifies three local
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5773 variables, @code{start}, @code{end}, and @code{newmark} and binds them
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5774 to the initial value @code{nil}. These variables are used inside the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5775 remainder of the @code{let} and temporarily hide any other occurrence of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5776 variables of the same name in Emacs until the end of the @code{let}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5777
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5778 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5779 The body of the @code{let} contains two @code{save-excursion}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5780 expressions. First, we will look at the inner @code{save-excursion}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5781 expression in detail. The expression looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5782
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5783 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5784 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5785 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5786 (set-buffer buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5787 (setq start (point-min) end (point-max)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5788 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5789 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5790
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5791 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5792 The expression @code{(set-buffer buffer)} changes Emacs' attention
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5793 from the current buffer to the one from which the text will copied.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5794 In that buffer, the variables @code{start} and @code{end} are set to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5795 the beginning and end of the buffer, using the commands
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5796 @code{point-min} and @code{point-max}. Note that we have here an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5797 illustration of how @code{setq} is able to set two variables in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5798 same expression. The first argument of @code{setq} is set to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5799 value of its second, and its third argument is set to the value of its
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5800 fourth.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5801
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5802 After the body of the inner @code{save-excursion} is evaluated, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5803 @code{save-excursion} restores the original buffer, but @code{start} and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5804 @code{end} remain set to the values of the beginning and end of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5805 buffer from which the text will be copied.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5806
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5807 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5808 The outer @code{save-excursion} expression looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5809
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5810 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5811 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5812 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5813 (@var{inner-}@code{save-excursion}@var{-expression}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5814 (@var{go-to-new-buffer-and-set-}@code{start}@var{-and-}@code{end})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5815 (insert-buffer-substring buffer start end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5816 (setq newmark (point)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5817 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5818 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5819
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5820 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5821 The @code{insert-buffer-substring} function copies the text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5822 @emph{into} the current buffer @emph{from} the region indicated by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5823 @code{start} and @code{end} in @code{buffer}. Since the whole of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5824 second buffer lies between @code{start} and @code{end}, the whole of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5825 the second buffer is copied into the buffer you are editing. Next,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5826 the value of point, which will be at the end of the inserted text, is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5827 recorded in the variable @code{newmark}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5828
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5829 After the body of the outer @code{save-excursion} is evaluated, point
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5830 and mark are relocated to their original places.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5831
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5832 However, it is convenient to locate a mark at the end of the newly
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5833 inserted text and locate point at its beginning. The @code{newmark}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5834 variable records the end of the inserted text. In the last line of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5835 the @code{let} expression, the @code{(push-mark newmark)} expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5836 function sets a mark to this location. (The previous location of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5837 mark is still accessible; it is recorded on the mark ring and you can
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5838 go back to it with @kbd{C-u C-@key{SPC}}.) Meanwhile, point is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5839 located at the beginning of the inserted text, which is where it was
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5840 before you called the insert function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5841
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5842 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5843 The whole @code{let} expression looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5844
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5845 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5846 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5847 (let (start end newmark)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5848 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5849 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5850 (set-buffer buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5851 (setq start (point-min) end (point-max)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5852 (insert-buffer-substring buffer start end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5853 (setq newmark (point)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5854 (push-mark newmark))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5855 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5856 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5857
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5858 Like the @code{append-to-buffer} function, the @code{insert-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5859 function uses @code{let}, @code{save-excursion}, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5860 @code{set-buffer}. In addition, the function illustrates one way to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5861 use @code{or}. All these functions are building blocks that we will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5862 find and use again and again.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5863
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5864 @node beginning-of-buffer, Second Buffer Related Review, insert-buffer, More Complex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5865 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5866 @section Complete Definition of @code{beginning-of-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5867 @findex beginning-of-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5868
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5869 The basic structure of the @code{beginning-of-buffer} function has
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5870 already been discussed. (@xref{simplified-beginning-of-buffer, , A
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5871 Simplified @code{beginning-of-buffer} Definition}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5872 This section describes the complex part of the definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5873
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5874 As previously described, when invoked without an argument,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5875 @code{beginning-of-buffer} moves the cursor to the beginning of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5876 buffer, leaving the mark at the previous position. However, when the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5877 command is invoked with a number between one and ten, the function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5878 considers that number to be a fraction of the length of the buffer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5879 measured in tenths, and Emacs moves the cursor that fraction of the way
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5880 from the beginning of the buffer. Thus, you can either call this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5881 function with the key command @kbd{M-<}, which will move the cursor to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5882 the beginning of the buffer, or with a key command such as @kbd{C-u 7
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5883 M-<} which will move the cursor to a point 70% of the way through the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5884 buffer. If a number bigger than ten is used for the argument, it moves
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5885 to the end of the buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5886
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5887 The @code{beginning-of-buffer} function can be called with or without an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5888 argument. The use of the argument is optional.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5889
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5890 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5891 * Optional Arguments::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5892 * beginning-of-buffer opt arg:: Example with optional argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5893 * beginning-of-buffer complete::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5894 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5895
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5896 @node Optional Arguments, beginning-of-buffer opt arg, beginning-of-buffer, beginning-of-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5897 @subsection Optional Arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5898
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5899 Unless told otherwise, Lisp expects that a function with an argument in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5900 its function definition will be called with a value for that argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5901 If that does not happen, you get an error and a message that says
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5902 @samp{Wrong number of arguments}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5903
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5904 @cindex Optional arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5905 @cindex Keyword
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5906 @findex optional
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5907 However, optional arguments are a feature of Lisp: a @dfn{keyword} may
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5908 be used to tell the Lisp interpreter that an argument is optional.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5909 The keyword is @code{&optional}. (The @samp{&} in front of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5910 @samp{optional} is part of the keyword.) In a function definition, if
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5911 an argument follows the keyword @code{&optional}, a value does not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5912 need to be passed to that argument when the function is called.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5913
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5914 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5915 The first line of the function definition of @code{beginning-of-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5916 therefore looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5917
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5918 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5919 (defun beginning-of-buffer (&optional arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5920 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5921
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5922 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5923 In outline, the whole function looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5924
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5925 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5926 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5927 (defun beginning-of-buffer (&optional arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5928 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5929 (interactive "P")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5930 (push-mark)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5931 (goto-char
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5932 (@var{if-there-is-an-argument}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5933 @var{figure-out-where-to-go}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5934 @var{else-go-to}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5935 (point-min))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5936 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5937 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5938
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5939 The function is similar to the @code{simplified-beginning-of-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5940 function except that the @code{interactive} expression has @code{"P"}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5941 as an argument and the @code{goto-char} function is followed by an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5942 if-then-else expression that figures out where to put the cursor if
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5943 there is an argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5944
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5945 The @code{"P"} in the @code{interactive} expression tells Emacs to pass
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5946 a prefix argument, if there is one, to the function. A prefix argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5947 is made by typing the @key{META} key followed by a number, or by typing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5948 @kbd{C-u} and then a number (if you don't type a number, @kbd{C-u}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5949 defaults to 4).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5950
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5951 The true-or-false-test of the @code{if} expression is simple: it is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5952 simply the argument @code{arg}. If @code{arg} has a value that is not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5953 @code{nil}, which will be the case if @code{beginning-of-buffer} is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5954 called with an argument, then this true-or-false-test will return true
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5955 and the then-part of the @code{if} expression will be evaluated. On the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5956 other hand, if @code{beginning-of-buffer} is not called with an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5957 argument, the value of @code{arg} will be @code{nil} and the else-part
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5958 of the @code{if} expression will be evaluated. The else-part is simply
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5959 @code{point-min}, and when this is the outcome, the whole
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5960 @code{goto-char} expression is @code{(goto-char (point-min))}, which is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5961 how we saw the @code{beginning-of-buffer} function in its simplified
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5962 form.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5963
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5964 @node beginning-of-buffer opt arg, beginning-of-buffer complete, Optional Arguments, beginning-of-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5965 @subsection @code{beginning-of-buffer} with an Argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5966
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5967 When @code{beginning-of-buffer} is called with an argument, an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5968 expression is evaluated which calculates what value to pass to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5969 @code{goto-char}. This expression is rather complicated at first sight.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5970 It includes an inner @code{if} expression and much arithmetic. It looks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5971 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5972
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5973 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5974 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5975 (if (> (buffer-size) 10000)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5976 ;; @r{Avoid overflow for large buffer sizes!}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5977 (* (prefix-numeric-value arg) (/ (buffer-size) 10))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5978 (/
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5979 (+ 10
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5980 (*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5981 (buffer-size) (prefix-numeric-value arg))) 10))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5982 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5983 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5984
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5985 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5986 * Disentangle beginning-of-buffer::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5987 * Large buffer case::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5988 * Small buffer case::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5989 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5990
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5991 @node Disentangle beginning-of-buffer, Large buffer case, beginning-of-buffer opt arg, beginning-of-buffer opt arg
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5992 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5993 @unnumberedsubsubsec Disentangle @code{beginning-of-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5994 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5995
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5996 Like other complex-looking expressions, the conditional expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5997 within @code{beginning-of-buffer} can be disentangled by looking at it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5998 as parts of a template, in this case, the template for an if-then-else
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5999 expression. In skeletal form, the expression looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6001 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6002 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6003 (if (@var{buffer-is-large}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6004 @var{divide-buffer-size-by-10-and-multiply-by-arg}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6005 @var{else-use-alternate-calculation}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6006 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6007 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6008
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6009 The true-or-false-test of this inner @code{if} expression checks the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6010 size of the buffer. The reason for this is that the old Version 18
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6011 Emacs used numbers that are no bigger than eight million or so
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6012 and in the computation that followed, the programmer feared that Emacs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6013 might try to use over-large numbers if the buffer were large. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6014 term `overflow', mentioned in the comment, means numbers that are over
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6015 large. Version 21 Emacs uses larger numbers, but this code has not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6016 been touched, if only because people now look at buffers that are far,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6017 far larger than ever before.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6018
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6019 There are two cases: if the buffer is large and if it is not.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6020
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6021 @node Large buffer case, Small buffer case, Disentangle beginning-of-buffer, beginning-of-buffer opt arg
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6022 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6023 @unnumberedsubsubsec What happens in a large buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6024
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6025 In @code{beginning-of-buffer}, the inner @code{if} expression tests
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6026 whether the size of the buffer is greater than 10,000 characters. To do
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6027 this, it uses the @code{>} function and the @code{buffer-size} function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6028
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6029 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6030 The line looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6031
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6032 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6033 (if (> (buffer-size) 10000)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6034 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6035
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6036 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6037 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6038 When the buffer is large, the then-part of the @code{if} expression is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6039 evaluated. It reads like this (after formatting for easy reading):
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6040
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6041 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6042 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6043 (*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6044 (prefix-numeric-value arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6045 (/ (buffer-size) 10))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6046 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6047 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6048
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6049 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6050 This expression is a multiplication, with two arguments to the function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6051 @code{*}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6052
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6053 The first argument is @code{(prefix-numeric-value arg)}. When
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6054 @code{"P"} is used as the argument for @code{interactive}, the value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6055 passed to the function as its argument is passed a ``raw prefix
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6056 argument'', and not a number. (It is a number in a list.) To perform
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6057 the arithmetic, a conversion is necessary, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6058 @code{prefix-numeric-value} does the job.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6059
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6060 @findex / @r{(division)}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6061 @cindex Division
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6062 The second argument is @code{(/ (buffer-size) 10)}. This expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6063 divides the numeric value of the buffer by ten. This produces a number
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6064 that tells how many characters make up one tenth of the buffer size.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6065 (In Lisp, @code{/} is used for division, just as @code{*} is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6066 used for multiplication.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6067
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6068 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6069 In the multiplication expression as a whole, this amount is multiplied
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6070 by the value of the prefix argument---the multiplication looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6071
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6072 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6073 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6074 (* @var{numeric-value-of-prefix-arg}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6075 @var{number-of-characters-in-one-tenth-of-the-buffer})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6076 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6077 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6078
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6079 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6080 If, for example, the prefix argument is @samp{7}, the one-tenth value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6081 will be multiplied by 7 to give a position 70% of the way through the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6082 buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6083
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6084 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6085 The result of all this is that if the buffer is large, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6086 @code{goto-char} expression reads like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6087
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6088 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6089 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6090 (goto-char (* (prefix-numeric-value arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6091 (/ (buffer-size) 10)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6092 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6093 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6094
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6095 This puts the cursor where we want it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6096
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6097 @node Small buffer case, , Large buffer case, beginning-of-buffer opt arg
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6098 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6099 @unnumberedsubsubsec What happens in a small buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6100
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6101 If the buffer contains fewer than 10,000 characters, a slightly
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6102 different computation is performed. You might think this is not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6103 necessary, since the first computation could do the job. However, in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6104 a small buffer, the first method may not put the cursor on exactly the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6105 desired line; the second method does a better job.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6106
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6107 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6108 The code looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6109
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6110 @c Keep this on one line.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6111 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6112 (/ (+ 10 (* (buffer-size) (prefix-numeric-value arg))) 10))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6113 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6114
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6115 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6116 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6117 This is code in which you figure out what happens by discovering how the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6118 functions are embedded in parentheses. It is easier to read if you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6119 reformat it with each expression indented more deeply than its
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6120 enclosing expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6121
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6122 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6123 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6124 (/
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6125 (+ 10
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6126 (*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6127 (buffer-size)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6128 (prefix-numeric-value arg)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6129 10))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6130 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6131 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6132
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6133 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6134 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6135 Looking at parentheses, we see that the innermost operation is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6136 @code{(prefix-numeric-value arg)}, which converts the raw argument to a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6137 number. This number is multiplied by the buffer size in the following
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6138 expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6139
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6140 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6141 (* (buffer-size) (prefix-numeric-value arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6142 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6143
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6144 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6145 This multiplication creates a number that may be larger than the size of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6146 the buffer---seven times larger if the argument is 7, for example. Ten
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6147 is then added to this number and finally the large number is divided by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6148 ten to provide a value that is one character larger than the percentage
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6149 position in the buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6150
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6151 The number that results from all this is passed to @code{goto-char} and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6152 the cursor is moved to that point.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6153
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6154 @node beginning-of-buffer complete, , beginning-of-buffer opt arg, beginning-of-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6155 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6156 @subsection The Complete @code{beginning-of-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6157
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6158 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6159 Here is the complete text of the @code{beginning-of-buffer} function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6160
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6161 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6162 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6163 (defun beginning-of-buffer (&optional arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6164 "Move point to the beginning of the buffer;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6165 leave mark at previous position.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6166 With arg N, put point N/10 of the way
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6167 from the true beginning.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6168 Don't use this in Lisp programs!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6169 \(goto-char (point-min)) is faster
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6170 and does not set the mark."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6171 (interactive "P")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6172 (push-mark)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6173 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6174 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6175 (goto-char
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6176 (if arg
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6177 (if (> (buffer-size) 10000)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6178 ;; @r{Avoid overflow for large buffer sizes!}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6179 (* (prefix-numeric-value arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6180 (/ (buffer-size) 10))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6181 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6182 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6183 (/ (+ 10 (* (buffer-size)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6184 (prefix-numeric-value arg)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6185 10))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6186 (point-min)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6187 (if arg (forward-line 1)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6188 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6189 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6190
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6191 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6192 Except for two small points, the previous discussion shows how this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6193 function works. The first point deals with a detail in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6194 documentation string, and the second point concerns the last line of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6195 the function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6196
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6197 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6198 In the documentation string, there is reference to an expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6199
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6200 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6201 \(goto-char (point-min))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6202 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6203
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6204 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6205 A @samp{\} is used before the first parenthesis of this expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6206 This @samp{\} tells the Lisp interpreter that the expression should be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6207 printed as shown in the documentation rather than evaluated as a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6208 symbolic expression, which is what it looks like.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6209
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6210 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6211 Finally, the last line of the @code{beginning-of-buffer} command says to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6212 move point to the beginning of the next line if the command is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6213 invoked with an argument:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6214
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6215 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6216 (if arg (forward-line 1)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6217 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6218
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6219 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6220 This puts the cursor at the beginning of the first line after the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6221 appropriate tenths position in the buffer. This is a flourish that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6222 means that the cursor is always located @emph{at least} the requested
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6223 tenths of the way through the buffer, which is a nicety that is,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6224 perhaps, not necessary, but which, if it did not occur, would be sure to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6225 draw complaints.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6226
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6227 @node Second Buffer Related Review, optional Exercise, beginning-of-buffer, More Complex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6228 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6229 @section Review
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6230
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6231 Here is a brief summary of some of the topics covered in this chapter.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6232
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6233 @table @code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6234 @item or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6235 Evaluate each argument in sequence, and return the value of the first
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6236 argument that is not @code{nil}; if none return a value that is not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6237 @code{nil}, return @code{nil}. In brief, return the first true value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6238 of the arguments; return a true value if one @emph{or} any of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6239 other are true.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6240
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6241 @item and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6242 Evaluate each argument in sequence, and if any are @code{nil}, return
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6243 @code{nil}; if none are @code{nil}, return the value of the last
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6244 argument. In brief, return a true value only if all the arguments are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6245 true; return a true value if one @emph{and} each of the others is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6246 true.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6247
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6248 @item &optional
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6249 A keyword used to indicate that an argument to a function definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6250 is optional; this means that the function can be evaluated without the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6251 argument, if desired.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6252
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6253 @item prefix-numeric-value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6254 Convert the `raw prefix argument' produced by @code{(interactive
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6255 "P")} to a numeric value.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6256
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6257 @item forward-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6258 Move point forward to the beginning of the next line, or if the argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6259 is greater than one, forward that many lines. If it can't move as far
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6260 forward as it is supposed to, @code{forward-line} goes forward as far as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6261 it can and then returns a count of the number of additional lines it was
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6262 supposed to move but couldn't.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6263
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6264 @item erase-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6265 Delete the entire contents of the current buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6266
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6267 @item bufferp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6268 Return @code{t} if its argument is a buffer; otherwise return @code{nil}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6269 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6270
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6271 @node optional Exercise, , Second Buffer Related Review, More Complex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6272 @section @code{optional} Argument Exercise
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6273
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6274 Write an interactive function with an optional argument that tests
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6275 whether its argument, a number, is greater or less than the value of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6276 @code{fill-column}, and tells you which, in a message. However, if you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6277 do not pass an argument to the function, use 56 as a default value.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6278
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6279 @node Narrowing & Widening, car cdr & cons, More Complex, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6280 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6281 @chapter Narrowing and Widening
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6282 @cindex Focusing attention (narrowing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6283 @cindex Narrowing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6284 @cindex Widening
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6285
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6286 Narrowing is a feature of Emacs that makes it possible for you to focus
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6287 on a specific part of a buffer, and work without accidentally changing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6288 other parts. Narrowing is normally disabled since it can confuse
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6289 novices.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6290
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6291 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6292 * Narrowing advantages:: The advantages of narrowing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6293 * save-restriction:: The @code{save-restriction} special form.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6294 * what-line:: The number of the line that point is on.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6295 * narrow Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6296 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6297
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6298 @node Narrowing advantages, save-restriction, Narrowing & Widening, Narrowing & Widening
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6299 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6300 @unnumberedsec The Advantages of Narrowing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6301 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6302
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6303 With narrowing, the rest of a buffer is made invisible, as if it weren't
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6304 there. This is an advantage if, for example, you want to replace a word
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6305 in one part of a buffer but not in another: you narrow to the part you want
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6306 and the replacement is carried out only in that section, not in the rest
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6307 of the buffer. Searches will only work within a narrowed region, not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6308 outside of one, so if you are fixing a part of a document, you can keep
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6309 yourself from accidentally finding parts you do not need to fix by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6310 narrowing just to the region you want.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6311 (The key binding for @code{narrow-to-region} is @kbd{C-x n n}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6312
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6313 However, narrowing does make the rest of the buffer invisible, which
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6314 can scare people who inadvertently invoke narrowing and think they
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6315 have deleted a part of their file. Moreover, the @code{undo} command
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6316 (which is usually bound to @kbd{C-x u}) does not turn off narrowing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6317 (nor should it), so people can become quite desperate if they do not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6318 know that they can return the rest of a buffer to visibility with the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6319 @code{widen} command.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6320 (The key binding for @code{widen} is @kbd{C-x n w}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6321
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6322 Narrowing is just as useful to the Lisp interpreter as to a human.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6323 Often, an Emacs Lisp function is designed to work on just part of a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6324 buffer; or conversely, an Emacs Lisp function needs to work on all of a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6325 buffer that has been narrowed. The @code{what-line} function, for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6326 example, removes the narrowing from a buffer, if it has any narrowing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6327 and when it has finished its job, restores the narrowing to what it was.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6328 On the other hand, the @code{count-lines} function, which is called by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6329 @code{what-line}, uses narrowing to restrict itself to just that portion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6330 of the buffer in which it is interested and then restores the previous
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6331 situation.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6332
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6333 @node save-restriction, what-line, Narrowing advantages, Narrowing & Widening
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6334 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6335 @section The @code{save-restriction} Special Form
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6336 @findex save-restriction
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6337
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6338 In Emacs Lisp, you can use the @code{save-restriction} special form to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6339 keep track of whatever narrowing is in effect, if any. When the Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6340 interpreter meets with @code{save-restriction}, it executes the code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6341 in the body of the @code{save-restriction} expression, and then undoes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6342 any changes to narrowing that the code caused. If, for example, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6343 buffer is narrowed and the code that follows @code{save-restriction}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6344 gets rid of the narrowing, @code{save-restriction} returns the buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6345 to its narrowed region afterwards. In the @code{what-line} command,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6346 any narrowing the buffer may have is undone by the @code{widen}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6347 command that immediately follows the @code{save-restriction} command.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6348 Any original narrowing is restored just before the completion of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6349 function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6350
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6351 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6352 The template for a @code{save-restriction} expression is simple:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6353
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6354 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6355 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6356 (save-restriction
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6357 @var{body}@dots{} )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6358 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6359 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6360
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6361 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6362 The body of the @code{save-restriction} is one or more expressions that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6363 will be evaluated in sequence by the Lisp interpreter.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6364
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6365 Finally, a point to note: when you use both @code{save-excursion} and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6366 @code{save-restriction}, one right after the other, you should use
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6367 @code{save-excursion} outermost. If you write them in reverse order,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6368 you may fail to record narrowing in the buffer to which Emacs switches
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6369 after calling @code{save-excursion}. Thus, when written together,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6370 @code{save-excursion} and @code{save-restriction} should be written
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6371 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6372
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6373 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6374 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6375 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6376 (save-restriction
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6377 @var{body}@dots{}))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6378 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6379 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6380
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6381 In other circumstances, when not written together, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6382 @code{save-excursion} and @code{save-restriction} special forms must
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6383 be written in the order appropriate to the function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6384
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6385 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6386 For example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6387
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6388 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6389 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6390 (save-restriction
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6391 (widen)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6392 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6393 @var{body}@dots{}))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6394 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6395 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6396
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6397 @node what-line, narrow Exercise, save-restriction, Narrowing & Widening
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6398 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6399 @section @code{what-line}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6400 @findex what-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6401 @cindex Widening, example of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6402
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6403 The @code{what-line} command tells you the number of the line in which
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6404 the cursor is located. The function illustrates the use of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6405 @code{save-restriction} and @code{save-excursion} commands. Here is the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6406 text of the function in full:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6407
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6408 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6409 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6410 (defun what-line ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6411 "Print the current line number (in the buffer) of point."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6412 (interactive)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6413 (save-restriction
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6414 (widen)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6415 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6416 (beginning-of-line)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6417 (message "Line %d"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6418 (1+ (count-lines 1 (point)))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6419 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6420 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6422 The function has a documentation line and is interactive, as you would
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6423 expect. The next two lines use the functions @code{save-restriction} and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6424 @code{widen}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6425
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6426 The @code{save-restriction} special form notes whatever narrowing is in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6427 effect, if any, in the current buffer and restores that narrowing after
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6428 the code in the body of the @code{save-restriction} has been evaluated.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6429
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6430 The @code{save-restriction} special form is followed by @code{widen}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6431 This function undoes any narrowing the current buffer may have had
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6432 when @code{what-line} was called. (The narrowing that was there is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6433 the narrowing that @code{save-restriction} remembers.) This widening
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6434 makes it possible for the line counting commands to count from the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6435 beginning of the buffer. Otherwise, they would have been limited to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6436 counting within the accessible region. Any original narrowing is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6437 restored just before the completion of the function by the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6438 @code{save-restriction} special form.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6439
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6440 The call to @code{widen} is followed by @code{save-excursion}, which
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6441 saves the location of the cursor (i.e., of point) and of the mark, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6442 restores them after the code in the body of the @code{save-excursion}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6443 uses the @code{beginning-of-line} function to move point.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6444
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6445 (Note that the @code{(widen)} expression comes between the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6446 @code{save-restriction} and @code{save-excursion} special forms. When
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6447 you write the two @code{save- @dots{}} expressions in sequence, write
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6448 @code{save-excursion} outermost.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6449
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6450 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6451 The last two lines of the @code{what-line} function are functions to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6452 count the number of lines in the buffer and then print the number in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6453 echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6454
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6455 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6456 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6457 (message "Line %d"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6458 (1+ (count-lines 1 (point)))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6459 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6460 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6461
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6462 The @code{message} function prints a one-line message at the bottom of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6463 Emacs screen. The first argument is inside of quotation marks and is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6464 printed as a string of characters. However, it may contain @samp{%d},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6465 @samp{%s}, or @samp{%c} to print arguments that follow the string.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6466 @samp{%d} prints the argument as a decimal, so the message will say
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6467 something such as @samp{Line 243}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6468
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6469 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6470 The number that is printed in place of the @samp{%d} is computed by the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6471 last line of the function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6472
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6473 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6474 (1+ (count-lines 1 (point)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6475 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6476
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6477 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6478 What this does is count the lines from the first position of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6479 buffer, indicated by the @code{1}, up to @code{(point)}, and then add
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6480 one to that number. (The @code{1+} function adds one to its
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6481 argument.) We add one to it because line 2 has only one line before
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6482 it, and @code{count-lines} counts only the lines @emph{before} the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6483 current line.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6484
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6485 After @code{count-lines} has done its job, and the message has been
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6486 printed in the echo area, the @code{save-excursion} restores point and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6487 mark to their original positions; and @code{save-restriction} restores
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6488 the original narrowing, if any.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6489
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6490 @node narrow Exercise, , what-line, Narrowing & Widening
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6491 @section Exercise with Narrowing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6492
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6493 Write a function that will display the first 60 characters of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6494 current buffer, even if you have narrowed the buffer to its latter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6495 half so that the first line is inaccessible. Restore point, mark,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6496 and narrowing. For this exercise, you need to use
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6497 @code{save-restriction}, @code{widen}, @code{goto-char},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6498 @code{point-min}, @code{buffer-substring}, @code{message}, and other
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6499 functions, a whole potpourri.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6501 @node car cdr & cons, Cutting & Storing Text, Narrowing & Widening, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6502 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6503 @chapter @code{car}, @code{cdr}, @code{cons}: Fundamental Functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6504 @findex car, @r{introduced}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6505 @findex cdr, @r{introduced}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6506
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6507 In Lisp, @code{car}, @code{cdr}, and @code{cons} are fundamental
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6508 functions. The @code{cons} function is used to construct lists, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6509 the @code{car} and @code{cdr} functions are used to take them apart.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6510
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6511 In the walk through of the @code{copy-region-as-kill} function, we
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6512 will see @code{cons} as well as two variants on @code{cdr},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6513 namely, @code{setcdr} and @code{nthcdr}. (@xref{copy-region-as-kill}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6514
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6515 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6516 * Strange Names:: An historical aside: why the strange names?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6517 * car & cdr:: Functions for extracting part of a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6518 * cons:: Constructing a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6519 * nthcdr:: Calling @code{cdr} repeatedly.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6520 * nth::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6521 * setcar:: Changing the first element of a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6522 * setcdr:: Changing the rest of a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6523 * cons Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6524 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6525
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6526 @node Strange Names, car & cdr, car cdr & cons, car cdr & cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6527 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6528 @unnumberedsec Strange Names
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6529 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6530
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6531 The name of the @code{cons} function is not unreasonable: it is an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6532 abbreviation of the word `construct'. The origins of the names for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6533 @code{car} and @code{cdr}, on the other hand, are esoteric: @code{car}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6534 is an acronym from the phrase `Contents of the Address part of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6535 Register'; and @code{cdr} (pronounced `could-er') is an acronym from
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6536 the phrase `Contents of the Decrement part of the Register'. These
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6537 phrases refer to specific pieces of hardware on the very early
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6538 computer on which the original Lisp was developed. Besides being
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6539 obsolete, the phrases have been completely irrelevant for more than 25
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6540 years to anyone thinking about Lisp. Nonetheless, although a few
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6541 brave scholars have begun to use more reasonable names for these
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6542 functions, the old terms are still in use. In particular, since the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6543 terms are used in the Emacs Lisp source code, we will use them in this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6544 introduction.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6545
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6546 @node car & cdr, cons, Strange Names, car cdr & cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6547 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6548 @section @code{car} and @code{cdr}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6549
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6550 The @sc{car} of a list is, quite simply, the first item in the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6551 Thus the @sc{car} of the list @code{(rose violet daisy buttercup)} is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6552 @code{rose}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6553
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6554 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6555 If you are reading this in Info in GNU Emacs, you can see this by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6556 evaluating the following:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6557
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6558 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6559 (car '(rose violet daisy buttercup))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6560 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6561
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6562 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6563 After evaluating the expression, @code{rose} will appear in the echo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6564 area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6565
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6566 Clearly, a more reasonable name for the @code{car} function would be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6567 @code{first} and this is often suggested.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6568
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6569 @code{car} does not remove the first item from the list; it only reports
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6570 what it is. After @code{car} has been applied to a list, the list is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6571 still the same as it was. In the jargon, @code{car} is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6572 `non-destructive'. This feature turns out to be important.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6573
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6574 The @sc{cdr} of a list is the rest of the list, that is, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6575 @code{cdr} function returns the part of the list that follows the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6576 first item. Thus, while the @sc{car} of the list @code{'(rose violet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6577 daisy buttercup)} is @code{rose}, the rest of the list, the value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6578 returned by the @code{cdr} function, is @code{(violet daisy
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6579 buttercup)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6580
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6581 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6582 You can see this by evaluating the following in the usual way:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6583
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6584 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6585 (cdr '(rose violet daisy buttercup))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6586 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6587
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6588 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6589 When you evaluate this, @code{(violet daisy buttercup)} will appear in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6590 the echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6591
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6592 Like @code{car}, @code{cdr} does not remove any elements from the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6593 list---it just returns a report of what the second and subsequent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6594 elements are.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6595
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6596 Incidentally, in the example, the list of flowers is quoted. If it were
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6597 not, the Lisp interpreter would try to evaluate the list by calling
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6598 @code{rose} as a function. In this example, we do not want to do that.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6599
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6600 Clearly, a more reasonable name for @code{cdr} would be @code{rest}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6601
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6602 (There is a lesson here: when you name new functions, consider very
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6603 carefully what you are doing, since you may be stuck with the names
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6604 for far longer than you expect. The reason this document perpetuates
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6605 these names is that the Emacs Lisp source code uses them, and if I did
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6606 not use them, you would have a hard time reading the code; but do,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6607 please, try to avoid using these terms yourself. The people who come
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6608 after you will be grateful to you.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6609
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6610 When @code{car} and @code{cdr} are applied to a list made up of symbols,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6611 such as the list @code{(pine fir oak maple)}, the element of the list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6612 returned by the function @code{car} is the symbol @code{pine} without
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6613 any parentheses around it. @code{pine} is the first element in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6614 list. However, the @sc{cdr} of the list is a list itself, @code{(fir
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6615 oak maple)}, as you can see by evaluating the following expressions in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6616 the usual way:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6617
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6618 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6619 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6620 (car '(pine fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6621
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6622 (cdr '(pine fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6623 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6624 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6625
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6626 On the other hand, in a list of lists, the first element is itself a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6627 list. @code{car} returns this first element as a list. For example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6628 the following list contains three sub-lists, a list of carnivores, a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6629 list of herbivores and a list of sea mammals:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6630
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6631 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6632 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6633 (car '((lion tiger cheetah)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6634 (gazelle antelope zebra)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6635 (whale dolphin seal)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6636 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6637 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6638
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6639 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6640 In this example, the first element or @sc{car} of the list is the list of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6641 carnivores, @code{(lion tiger cheetah)}, and the rest of the list is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6642 @code{((gazelle antelope zebra) (whale dolphin seal))}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6643
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6644 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6645 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6646 (cdr '((lion tiger cheetah)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6647 (gazelle antelope zebra)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6648 (whale dolphin seal)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6649 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6650 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6651
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6652 It is worth saying again that @code{car} and @code{cdr} are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6653 non-destructive---that is, they do not modify or change lists to which
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6654 they are applied. This is very important for how they are used.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6655
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6656 Also, in the first chapter, in the discussion about atoms, I said that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6657 in Lisp, ``certain kinds of atom, such as an array, can be separated
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6658 into parts; but the mechanism for doing this is different from the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6659 mechanism for splitting a list. As far as Lisp is concerned, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6660 atoms of a list are unsplittable.'' (@xref{Lisp Atoms}.) The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6661 @code{car} and @code{cdr} functions are used for splitting lists and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6662 are considered fundamental to Lisp. Since they cannot split or gain
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6663 access to the parts of an array, an array is considered an atom.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6664 Conversely, the other fundamental function, @code{cons}, can put
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6665 together or construct a list, but not an array. (Arrays are handled
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6666 by array-specific functions. @xref{Arrays, , Arrays, elisp, The GNU
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6667 Emacs Lisp Reference Manual}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6668
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6669 @node cons, nthcdr, car & cdr, car cdr & cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6670 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6671 @section @code{cons}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6672 @findex cons, @r{introduced}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6673
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6674 The @code{cons} function constructs lists; it is the inverse of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6675 @code{car} and @code{cdr}. For example, @code{cons} can be used to make
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6676 a four element list from the three element list, @code{(fir oak maple)}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6677
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6678 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6679 (cons 'pine '(fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6680 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6681
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6682 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6683 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6684 After evaluating this list, you will see
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6685
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6686 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6687 (pine fir oak maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6688 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6689
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6690 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6691 appear in the echo area. @code{cons} puts a new element at the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6692 beginning of a list; it attaches or pushes elements onto the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6693
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6694 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6695 * Build a list::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6696 * length:: How to find the length of a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6697 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6698
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6699 @node Build a list, length, cons, cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6700 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6701 @unnumberedsubsec Build a list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6702 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6703
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6704 @code{cons} must have a list to attach to.@footnote{Actually, you can
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6705 @code{cons} an element to an atom to produce a dotted pair. Dotted
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6706 pairs are not discussed here; see @ref{Dotted Pair Notation, , Dotted
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6707 Pair Notation, elisp, The GNU Emacs Lisp Reference Manual}.} You
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6708 cannot start from absolutely nothing. If you are building a list, you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6709 need to provide at least an empty list at the beginning. Here is a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6710 series of @code{cons} expressions that build up a list of flowers. If
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6711 you are reading this in Info in GNU Emacs, you can evaluate each of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6712 the expressions in the usual way; the value is printed in this text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6713 after @samp{@result{}}, which you may read as `evaluates to'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6714
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6715 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6716 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6717 (cons 'buttercup ())
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6718 @result{} (buttercup)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6719 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6720
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6721 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6722 (cons 'daisy '(buttercup))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6723 @result{} (daisy buttercup)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6724 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6725
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6726 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6727 (cons 'violet '(daisy buttercup))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6728 @result{} (violet daisy buttercup)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6729 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6730
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6731 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6732 (cons 'rose '(violet daisy buttercup))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6733 @result{} (rose violet daisy buttercup)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6734 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6735 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6736
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6737 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6738 In the first example, the empty list is shown as @code{()} and a list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6739 made up of @code{buttercup} followed by the empty list is constructed.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6740 As you can see, the empty list is not shown in the list that was
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6741 constructed. All that you see is @code{(buttercup)}. The empty list is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6742 not counted as an element of a list because there is nothing in an empty
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6743 list. Generally speaking, an empty list is invisible.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6744
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6745 The second example, @code{(cons 'daisy '(buttercup))} constructs a new,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6746 two element list by putting @code{daisy} in front of @code{buttercup};
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6747 and the third example constructs a three element list by putting
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6748 @code{violet} in front of @code{daisy} and @code{buttercup}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6749
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6750 @node length, , Build a list, cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6751 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6752 @subsection Find the Length of a List: @code{length}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6753 @findex length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6754
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6755 You can find out how many elements there are in a list by using the Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6756 function @code{length}, as in the following examples:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6757
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6758 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6759 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6760 (length '(buttercup))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6761 @result{} 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6762 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6763
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6764 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6765 (length '(daisy buttercup))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6766 @result{} 2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6767 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6768
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6769 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6770 (length (cons 'violet '(daisy buttercup)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6771 @result{} 3
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6772 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6773 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6774
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6775 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6776 In the third example, the @code{cons} function is used to construct a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6777 three element list which is then passed to the @code{length} function as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6778 its argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6779
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6780 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6781 We can also use @code{length} to count the number of elements in an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6782 empty list:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6783
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6784 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6785 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6786 (length ())
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6787 @result{} 0
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6788 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6789 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6790
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6791 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6792 As you would expect, the number of elements in an empty list is zero.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6793
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6794 An interesting experiment is to find out what happens if you try to find
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6795 the length of no list at all; that is, if you try to call @code{length}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6796 without giving it an argument, not even an empty list:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6797
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6798 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6799 (length )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6800 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6801
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6802 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6803 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6804 What you see, if you evaluate this, is the error message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6805
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6806 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6807 Wrong number of arguments: #<subr length>, 0
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6808 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6809
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6810 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6811 This means that the function receives the wrong number of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6812 arguments, zero, when it expects some other number of arguments. In
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6813 this case, one argument is expected, the argument being a list whose
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6814 length the function is measuring. (Note that @emph{one} list is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6815 @emph{one} argument, even if the list has many elements inside it.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6816
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6817 The part of the error message that says @samp{#<subr length>} is the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6818 name of the function. This is written with a special notation,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6819 @samp{#<subr}, that indicates that the function @code{length} is one
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6820 of the primitive functions written in C rather than in Emacs Lisp.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6821 (@samp{subr} is an abbreviation for `subroutine'.) @xref{What Is a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6822 Function, , What Is a Function?, elisp , The GNU Emacs Lisp Reference
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6823 Manual}, for more about subroutines.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6824
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6825 @node nthcdr, nth, cons, car cdr & cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6826 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6827 @section @code{nthcdr}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6828 @findex nthcdr
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6829
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6830 The @code{nthcdr} function is associated with the @code{cdr} function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6831 What it does is take the @sc{cdr} of a list repeatedly.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6832
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6833 If you take the @sc{cdr} of the list @code{(pine fir
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6834 oak maple)}, you will be returned the list @code{(fir oak maple)}. If you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6835 repeat this on what was returned, you will be returned the list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6836 @code{(oak maple)}. (Of course, repeated @sc{cdr}ing on the original
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6837 list will just give you the original @sc{cdr} since the function does
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6838 not change the list. You need to evaluate the @sc{cdr} of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6839 @sc{cdr} and so on.) If you continue this, eventually you will be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6840 returned an empty list, which in this case, instead of being shown as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6841 @code{()} is shown as @code{nil}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6842
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6843 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6844 For review, here is a series of repeated @sc{cdr}s, the text following
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6845 the @samp{@result{}} shows what is returned.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6846
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6847 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6848 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6849 (cdr '(pine fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6850 @result{}(fir oak maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6851 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6852
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6853 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6854 (cdr '(fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6855 @result{} (oak maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6856 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6857
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6858 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6859 (cdr '(oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6860 @result{}(maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6861 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6862
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6863 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6864 (cdr '(maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6865 @result{} nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6866 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6867
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6868 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6869 (cdr 'nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6870 @result{} nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6871 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6872
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6873 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6874 (cdr ())
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6875 @result{} nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6876 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6877 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6878
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6879 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6880 You can also do several @sc{cdr}s without printing the values in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6881 between, like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6882
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6883 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6884 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6885 (cdr (cdr '(pine fir oak maple)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6886 @result{} (oak maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6887 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6888 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6889
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6890 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6891 In this example, the Lisp interpreter evaluates the innermost list first.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6892 The innermost list is quoted, so it just passes the list as it is to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6893 innermost @code{cdr}. This @code{cdr} passes a list made up of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6894 second and subsequent elements of the list to the outermost @code{cdr},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6895 which produces a list composed of the third and subsequent elements of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6896 the original list. In this example, the @code{cdr} function is repeated
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6897 and returns a list that consists of the original list without its
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6898 first two elements.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6899
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6900 The @code{nthcdr} function does the same as repeating the call to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6901 @code{cdr}. In the following example, the argument 2 is passed to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6902 function @code{nthcdr}, along with the list, and the value returned is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6903 the list without its first two items, which is exactly the same
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6904 as repeating @code{cdr} twice on the list:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6905
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6906 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6907 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6908 (nthcdr 2 '(pine fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6909 @result{} (oak maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6910 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6911 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6912
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6913 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6914 Using the original four element list, we can see what happens when
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6915 various numeric arguments are passed to @code{nthcdr}, including 0, 1,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6916 and 5:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6917
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6918 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6919 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6920 ;; @r{Leave the list as it was.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6921 (nthcdr 0 '(pine fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6922 @result{} (pine fir oak maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6923 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6924
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6925 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6926 ;; @r{Return a copy without the first element.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6927 (nthcdr 1 '(pine fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6928 @result{} (fir oak maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6929 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6930
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6931 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6932 ;; @r{Return a copy of the list without three elements.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6933 (nthcdr 3 '(pine fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6934 @result{} (maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6935 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6936
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6937 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6938 ;; @r{Return a copy lacking all four elements.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6939 (nthcdr 4 '(pine fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6940 @result{} nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6941 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6942
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6943 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6944 ;; @r{Return a copy lacking all elements.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6945 (nthcdr 5 '(pine fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6946 @result{} nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6947 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6948 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6949
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6950 @node nth, setcar, nthcdr, car cdr & cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6951 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6952 @section @code{nth}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6953 @findex nth
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6954
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6955 The @code{nthcdr} function takes the @sc{cdr} of a list repeatedly.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6956 The @code{nth} function takes the @sc{car} of the result returned by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6957 @code{nthcdr}. It returns the Nth element of the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6958
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6959 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6960 Thus, if it were not defined in C for speed, the definition of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6961 @code{nth} would be:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6962
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6963 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6964 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6965 (defun nth (n list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6966 "Returns the Nth element of LIST.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6967 N counts from zero. If LIST is not that long, nil is returned."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6968 (car (nthcdr n list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6969 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6970 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6971
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6972 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6973 (Originally, @code{nth} was defined in Emacs Lisp in @file{subr.el},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6974 but its definition was redone in C in the 1980s.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6975
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6976 The @code{nth} function returns a single element of a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6977 This can be very convenient.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6978
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6979 Note that the elements are numbered from zero, not one. That is to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6980 say, the first element of a list, its @sc{car} is the zeroth element.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6981 This is called `zero-based' counting and often bothers people who
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6982 are accustomed to the first element in a list being number one, which
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6983 is `one-based'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6984
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6985 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6986 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6987
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6988 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6989 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6990 (nth 0 '("one" "two" "three"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6991 @result{} "one"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6992
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6993 (nth 1 '("one" "two" "three"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6994 @result{} "two"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6995 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6996 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6997
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6998 It is worth mentioning that @code{nth}, like @code{nthcdr} and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6999 @code{cdr}, does not change the original list---the function is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7000 non-destructive. This is in sharp contrast to the @code{setcar} and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7001 @code{setcdr} functions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7002
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7003 @node setcar, setcdr, nth, car cdr & cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7004 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7005 @section @code{setcar}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7006 @findex setcar
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7007
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7008 As you might guess from their names, the @code{setcar} and @code{setcdr}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7009 functions set the @sc{car} or the @sc{cdr} of a list to a new value.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7010 They actually change the original list, unlike @code{car} and @code{cdr}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7011 which leave the original list as it was. One way to find out how this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7012 works is to experiment. We will start with the @code{setcar} function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7013
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7014 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7015 First, we can make a list and then set the value of a variable to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7016 list, using the @code{setq} function. Here is a list of animals:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7017
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7018 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7019 (setq animals '(antelope giraffe lion tiger))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7020 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7021
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7022 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7023 If you are reading this in Info inside of GNU Emacs, you can evaluate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7024 this expression in the usual fashion, by positioning the cursor after
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7025 the expression and typing @kbd{C-x C-e}. (I'm doing this right here as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7026 I write this. This is one of the advantages of having the interpreter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7027 built into the computing environment.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7028
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7029 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7030 When we evaluate the variable @code{animals}, we see that it is bound to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7031 the list @code{(antelope giraffe lion tiger)}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7032
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7033 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7034 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7035 animals
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7036 @result{} (antelope giraffe lion tiger)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7037 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7038 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7039
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7040 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7041 Put another way, the variable @code{animals} points to the list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7042 @code{(antelope giraffe lion tiger)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7043
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7044 Next, evaluate the function @code{setcar} while passing it two
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7045 arguments, the variable @code{animals} and the quoted symbol
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7046 @code{hippopotamus}; this is done by writing the three element list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7047 @code{(setcar animals 'hippopotamus)} and then evaluating it in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7048 usual fashion:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7049
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7050 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7051 (setcar animals 'hippopotamus)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7052 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7053
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7054 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7055 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7056 After evaluating this expression, evaluate the variable @code{animals}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7057 again. You will see that the list of animals has changed:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7058
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7059 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7060 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7061 animals
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7062 @result{} (hippopotamus giraffe lion tiger)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7063 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7064 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7065
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7066 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7067 The first element on the list, @code{antelope} is replaced by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7068 @code{hippopotamus}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7069
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7070 So we can see that @code{setcar} did not add a new element to the list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7071 as @code{cons} would have; it replaced @code{giraffe} with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7072 @code{hippopotamus}; it @emph{changed} the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7073
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7074 @node setcdr, cons Exercise, setcar, car cdr & cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7075 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7076 @section @code{setcdr}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7077 @findex setcdr
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7078
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7079 The @code{setcdr} function is similar to the @code{setcar} function,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7080 except that the function replaces the second and subsequent elements of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7081 a list rather than the first element.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7082
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7083 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7084 To see how this works, set the value of the variable to a list of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7085 domesticated animals by evaluating the following expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7086
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7087 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7088 (setq domesticated-animals '(horse cow sheep goat))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7089 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7090
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7091 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7092 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7093 If you now evaluate the list, you will be returned the list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7094 @code{(horse cow sheep goat)}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7095
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7096 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7097 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7098 domesticated-animals
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7099 @result{} (horse cow sheep goat)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7100 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7101 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7102
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7103 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7104 Next, evaluate @code{setcdr} with two arguments, the name of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7105 variable which has a list as its value, and the list to which the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7106 @sc{cdr} of the first list will be set;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7107
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7108 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7109 (setcdr domesticated-animals '(cat dog))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7110 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7111
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7112 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7113 If you evaluate this expression, the list @code{(cat dog)} will appear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7114 in the echo area. This is the value returned by the function. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7115 result we are interested in is the ``side effect'', which we can see by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7116 evaluating the variable @code{domesticated-animals}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7117
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7118 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7119 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7120 domesticated-animals
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7121 @result{} (horse cat dog)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7122 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7123 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7124
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7125 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7126 Indeed, the list is changed from @code{(horse cow sheep goat)} to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7127 @code{(horse cat dog)}. The @sc{cdr} of the list is changed from
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7128 @code{(cow sheep goat)} to @code{(cat dog)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7129
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7130 @node cons Exercise, , setcdr, car cdr & cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7131 @section Exercise
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7132
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7133 Construct a list of four birds by evaluating several expressions with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7134 @code{cons}. Find out what happens when you @code{cons} a list onto
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7135 itself. Replace the first element of the list of four birds with a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7136 fish. Replace the rest of that list with a list of other fish.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7137 @node Cutting & Storing Text, List Implementation, car cdr & cons, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7138 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7139 @chapter Cutting and Storing Text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7140 @cindex Cutting and storing text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7141 @cindex Storing and cutting text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7142 @cindex Killing text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7143 @cindex Clipping text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7144 @cindex Erasing text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7145 @cindex Deleting text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7146
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7147 Whenever you cut or clip text out of a buffer with a `kill' command in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7148 GNU Emacs, it is stored in a list and you can bring it back with a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7149 `yank' command.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7150
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7151 (The use of the word `kill' in Emacs for processes which specifically
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7152 @emph{do not} destroy the values of the entities is an unfortunate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7153 historical accident. A much more appropriate word would be `clip' since
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7154 that is what the kill commands do; they clip text out of a buffer and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7155 put it into storage from which it can be brought back. I have often
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7156 been tempted to replace globally all occurrences of `kill' in the Emacs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7157 sources with `clip' and all occurrences of `killed' with `clipped'.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7158
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7159 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7160 * Storing Text:: Text is stored in a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7161 * zap-to-char:: Cutting out text up to a character.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7162 * kill-region:: Cutting text out of a region.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7163 * Digression into C:: Minor note on C programming language macros.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7164 * defvar:: How to give a variable an initial value.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7165 * copy-region-as-kill:: A definition for copying text.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7166 * cons & search-fwd Review::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7167 * search Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7168 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7169
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7170 @node Storing Text, zap-to-char, Cutting & Storing Text, Cutting & Storing Text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7171 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7172 @unnumberedsec Storing Text in a List
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7173 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7174
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7175 When text is cut out of a buffer, it is stored on a list. Successive
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7176 pieces of text are stored on the list successively, so the list might
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7177 look like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7178
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7179 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7180 ("a piece of text" "previous piece")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7181 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7182
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7183 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7184 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7185 The function @code{cons} can be used to add a piece of text to the list,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7186 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7187
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7188 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7189 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7190 (cons "another piece"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7191 '("a piece of text" "previous piece"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7192 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7193 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7194
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7195 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7196 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7197 If you evaluate this expression, a list of three elements will appear in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7198 the echo area:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7199
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7200 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7201 ("another piece" "a piece of text" "previous piece")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7202 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7203
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7204 With the @code{car} and @code{nthcdr} functions, you can retrieve
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7205 whichever piece of text you want. For example, in the following code,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7206 @code{nthcdr 1 @dots{}} returns the list with the first item removed;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7207 and the @code{car} returns the first element of that remainder---the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7208 second element of the original list:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7209
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7210 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7211 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7212 (car (nthcdr 1 '("another piece"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7213 "a piece of text"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7214 "previous piece")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7215 @result{} "a piece of text"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7216 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7217 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7218
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7219 The actual functions in Emacs are more complex than this, of course.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7220 The code for cutting and retrieving text has to be written so that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7221 Emacs can figure out which element in the list you want---the first,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7222 second, third, or whatever. In addition, when you get to the end of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7223 the list, Emacs should give you the first element of the list, rather
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7224 than nothing at all.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7225
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7226 The list that holds the pieces of text is called the @dfn{kill ring}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7227 This chapter leads up to a description of the kill ring and how it is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7228 used by first tracing how the @code{zap-to-char} function works. This
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7229 function uses (or `calls') a function that invokes a function that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7230 manipulates the kill ring. Thus, before reaching the mountains, we
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7231 climb the foothills.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7232
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7233 A subsequent chapter describes how text that is cut from the buffer is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7234 retrieved. @xref{Yanking, , Yanking Text Back}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7235
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7236 @node zap-to-char, kill-region, Storing Text, Cutting & Storing Text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7237 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7238 @section @code{zap-to-char}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7239 @findex zap-to-char
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7240
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7241 The @code{zap-to-char} function barely changed between GNU Emacs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7242 version 19 and GNU Emacs version 21. However, @code{zap-to-char}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7243 calls another function, @code{kill-region}, which enjoyed a major rewrite
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7244 on the way to version 21.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7245
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7246 The @code{kill-region} function in Emacs 19 is complex, but does not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7247 use code that is important at this time. We will skip it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7248
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7249 The @code{kill-region} function in Emacs 21 is easier to read than the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7250 same function in Emacs 19 and introduces a very important concept,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7251 that of error handling. We will walk through the function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7252
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7253 But first, let us look at the interactive @code{zap-to-char} function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7254
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7255 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7256 * Complete zap-to-char:: The complete implementation.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7257 * zap-to-char interactive:: A three part interactive expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7258 * zap-to-char body:: A short overview.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7259 * search-forward:: How to search for a string.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7260 * progn:: The @code{progn} special form.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7261 * Summing up zap-to-char:: Using @code{point} and @code{search-forward}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7262 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7263
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7264 @node Complete zap-to-char, zap-to-char interactive, zap-to-char, zap-to-char
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7265 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7266 @unnumberedsubsec The Complete @code{zap-to-char} Implementation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7267 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7268
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7269 The GNU Emacs version 19 and version 21 implementations of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7270 @code{zap-to-char} function are nearly identical in form, and they
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7271 work alike. The function removes the text in the region between the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7272 location of the cursor (i.e., of point) up to and including the next
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7273 occurrence of a specified character. The text that @code{zap-to-char}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7274 removes is put in the kill ring; and it can be retrieved from the kill
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7275 ring by typing @kbd{C-y} (@code{yank}). If the command is given an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7276 argument, it removes text through that number of occurrences. Thus,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7277 if the cursor were at the beginning of this sentence and the character
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7278 were @samp{s}, @samp{Thus} would be removed. If the argument were
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7279 two, @samp{Thus, if the curs} would be removed, up to and including
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7280 the @samp{s} in @samp{cursor}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7281
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7282 If the specified character is not found, @code{zap-to-char} will say
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7283 ``Search failed'', tell you the character you typed, and not remove
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7284 any text.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7285
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7286 In order to determine how much text to remove, @code{zap-to-char} uses
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7287 a search function. Searches are used extensively in code that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7288 manipulates text, and we will focus attention on them as well as on the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7289 deletion command.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7290
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7291 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7292 Here is the complete text of the version 19 implementation of the function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7293
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7294 @c v 19
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7295 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7296 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7297 (defun zap-to-char (arg char) ; version 19 implementation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7298 "Kill up to and including ARG'th occurrence of CHAR.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7299 Goes backward if ARG is negative; error if CHAR not found."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7300 (interactive "*p\ncZap to char: ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7301 (kill-region (point)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7302 (progn
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7303 (search-forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7304 (char-to-string char) nil nil arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7305 (point))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7306 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7307 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7308
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7309 @node zap-to-char interactive, zap-to-char body, Complete zap-to-char, zap-to-char
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7310 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7311 @subsection The @code{interactive} Expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7312
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7313 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7314 The interactive expression in the @code{zap-to-char} command looks like
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7315 this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7316
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7317 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7318 (interactive "*p\ncZap to char: ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7319 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7320
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7321 The part within quotation marks, @code{"*p\ncZap to char:@: "}, specifies
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7322 three different things. First, and most simply, the asterisk, @samp{*},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7323 causes an error to be signalled if the buffer is read-only. This means that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7324 if you try @code{zap-to-char} in a read-only buffer you will not be able to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7325 remove text, and you will receive a message that says ``Buffer is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7326 read-only''; your terminal may beep at you as well.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7327
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7328 The version 21 implementation does not have the asterisk, @samp{*}. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7329 function works the same as in version 19: in both cases, it cannot
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7330 remove text from a read-only buffer but the function does copy the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7331 text that would have been removed to the kill ring. Also, in both
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7332 cases, you see an error message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7333
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7334 However, the version 19 implementation copies text from a read-only
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7335 buffer only because of a mistake in the implementation of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7336 @code{interactive}. According to the documentation for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7337 @code{interactive}, the asterisk, @samp{*}, should prevent the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7338 @code{zap-to-char} function from doing anything at all when the buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7339 is read only. The function should not copy the text to the kill ring.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7340 It is a bug that it does.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7341
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7342 In version 21, @code{interactive} is implemented correctly. So the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7343 asterisk, @samp{*}, had to be removed from the interactive
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7344 specification. If you insert an @samp{*} and evaluate the function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7345 definition, then the next time you run the @code{zap-to-char} function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7346 on a read-only buffer, you will not copy any text.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7347
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7348 That change aside, and a change to the documentation, the two versions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7349 of the @code{zap-to-char} function are identical.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7350
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7351 Let us continue with the interactive specification.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7352
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7353 The second part of @code{"*p\ncZap to char:@: "} is the @samp{p}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7354 This part is separated from the next part by a newline, @samp{\n}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7355 The @samp{p} means that the first argument to the function will be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7356 passed the value of a `processed prefix'. The prefix argument is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7357 passed by typing @kbd{C-u} and a number, or @kbd{M-} and a number. If
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7358 the function is called interactively without a prefix, 1 is passed to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7359 this argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7360
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7361 The third part of @code{"*p\ncZap to char:@: "} is @samp{cZap to char:@:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7362 }. In this part, the lower case @samp{c} indicates that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7363 @code{interactive} expects a prompt and that the argument will be a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7364 character. The prompt follows the @samp{c} and is the string @samp{Zap
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7365 to char:@: } (with a space after the colon to make it look good).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7366
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7367 What all this does is prepare the arguments to @code{zap-to-char} so they
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7368 are of the right type, and give the user a prompt.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7369
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7370 @node zap-to-char body, search-forward, zap-to-char interactive, zap-to-char
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7371 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7372 @subsection The Body of @code{zap-to-char}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7373
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7374 The body of the @code{zap-to-char} function contains the code that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7375 kills (that is, removes) the text in the region from the current
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7376 position of the cursor up to and including the specified character.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7377 The first part of the code looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7378
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7379 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7380 (kill-region (point) @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7381 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7382
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7383 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7384 @code{(point)} is the current position of the cursor.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7385
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7386 The next part of the code is an expression using @code{progn}. The body
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7387 of the @code{progn} consists of calls to @code{search-forward} and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7388 @code{point}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7389
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7390 It is easier to understand how @code{progn} works after learning about
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7391 @code{search-forward}, so we will look at @code{search-forward} and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7392 then at @code{progn}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7393
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7394 @node search-forward, progn, zap-to-char body, zap-to-char
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7395 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7396 @subsection The @code{search-forward} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7397 @findex search-forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7398
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7399 The @code{search-forward} function is used to locate the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7400 zapped-for-character in @code{zap-to-char}. If the search is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7401 successful, @code{search-forward} leaves point immediately after the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7402 last character in the target string. (In @code{zap-to-char}, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7403 target string is just one character long.) If the search is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7404 backwards, @code{search-forward} leaves point just before the first
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7405 character in the target. Also, @code{search-forward} returns @code{t}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7406 for true. (Moving point is therefore a `side effect'.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7407
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7408 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7409 In @code{zap-to-char}, the @code{search-forward} function looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7410
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7411 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7412 (search-forward (char-to-string char) nil nil arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7413 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7414
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7415 The @code{search-forward} function takes four arguments:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7416
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7417 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7418 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7419 The first argument is the target, what is searched for. This must be a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7420 string, such as @samp{"z"}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7422 As it happens, the argument passed to @code{zap-to-char} is a single
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7423 character. Because of the way computers are built, the Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7424 interpreter may treat a single character as being different from a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7425 string of characters. Inside the computer, a single character has a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7426 different electronic format than a string of one character. (A single
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7427 character can often be recorded in the computer using exactly one
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7428 byte; but a string may be longer, and the computer needs to be ready
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7429 for this.) Since the @code{search-forward} function searches for a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7430 string, the character that the @code{zap-to-char} function receives as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7431 its argument must be converted inside the computer from one format to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7432 the other; otherwise the @code{search-forward} function will fail.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7433 The @code{char-to-string} function is used to make this conversion.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7434
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7435 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7436 The second argument bounds the search; it is specified as a position in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7437 the buffer. In this case, the search can go to the end of the buffer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7438 so no bound is set and the second argument is @code{nil}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7439
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7440 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7441 The third argument tells the function what it should do if the search
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7442 fails---it can signal an error (and print a message) or it can return
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7443 @code{nil}. A @code{nil} as the third argument causes the function to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7444 signal an error when the search fails.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7445
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7446 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7447 The fourth argument to @code{search-forward} is the repeat count---how
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7448 many occurrences of the string to look for. This argument is optional
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7449 and if the function is called without a repeat count, this argument is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7450 passed the value 1. If this argument is negative, the search goes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7451 backwards.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7452 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7453
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7454 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7455 In template form, a @code{search-forward} expression looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7456
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7457 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7458 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7459 (search-forward "@var{target-string}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7460 @var{limit-of-search}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7461 @var{what-to-do-if-search-fails}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7462 @var{repeat-count})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7463 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7464 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7465
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7466 We will look at @code{progn} next.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7467
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7468 @node progn, Summing up zap-to-char, search-forward, zap-to-char
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7469 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7470 @subsection The @code{progn} Special Form
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7471 @findex progn
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7472
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7473 @code{progn} is a special form that causes each of its arguments to be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7474 evaluated in sequence and then returns the value of the last one. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7475 preceding expressions are evaluated only for the side effects they
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7476 perform. The values produced by them are discarded.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7477
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7478 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7479 The template for a @code{progn} expression is very simple:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7480
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7481 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7482 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7483 (progn
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7484 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7485 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7486 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7487
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7488 In @code{zap-to-char}, the @code{progn} expression has to do two things:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7489 put point in exactly the right position; and return the location of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7490 point so that @code{kill-region} will know how far to kill to.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7491
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7492 The first argument to the @code{progn} is @code{search-forward}. When
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7493 @code{search-forward} finds the string, the function leaves point
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7494 immediately after the last character in the target string. (In this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7495 case the target string is just one character long.) If the search is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7496 backwards, @code{search-forward} leaves point just before the first
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7497 character in the target. The movement of point is a side effect.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7498
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7499 The second and last argument to @code{progn} is the expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7500 @code{(point)}. This expression returns the value of point, which in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7501 this case will be the location to which it has been moved by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7502 @code{search-forward}. This value is returned by the @code{progn}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7503 expression and is passed to @code{kill-region} as @code{kill-region}'s
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7504 second argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7505
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7506 @node Summing up zap-to-char, , progn, zap-to-char
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7507 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7508 @subsection Summing up @code{zap-to-char}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7509
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7510 Now that we have seen how @code{search-forward} and @code{progn} work,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7511 we can see how the @code{zap-to-char} function works as a whole.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7512
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7513 The first argument to @code{kill-region} is the position of the cursor
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7514 when the @code{zap-to-char} command is given---the value of point at
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7515 that time. Within the @code{progn}, the search function then moves
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7516 point to just after the zapped-to-character and @code{point} returns the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7517 value of this location. The @code{kill-region} function puts together
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7518 these two values of point, the first one as the beginning of the region
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7519 and the second one as the end of the region, and removes the region.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7520
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7521 The @code{progn} special form is necessary because the @code{kill-region}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7522 command takes two arguments; and it would fail if @code{search-forward}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7523 and @code{point} expressions were written in sequence as two
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7524 additional arguments. The @code{progn} expression is a single argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7525 to @code{kill-region} and returns the one value that @code{kill-region}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7526 needs for its second argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7527
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7528 @node kill-region, Digression into C, zap-to-char, Cutting & Storing Text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7529 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7530 @section @code{kill-region}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7531 @findex kill-region
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7532
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7533 The @code{zap-to-char} function uses the @code{kill-region} function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7534 This function clips text from a region and copies that text to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7535 the kill ring, from which it may be retrieved.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7536
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7537 The Emacs 21 version of that function uses @code{condition-case} and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7538 @code{copy-region-as-kill}, both of which we will explain.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7539 @code{condition-case} is an important special form.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7540
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7541 In essence, the @code{kill-region} function calls
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7542 @code{condition-case}, which takes three arguments. In this function,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7543 the first argument does nothing. The second argument contains the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7544 code that does the work when all goes well. The third argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7545 contains the code that is called in the event of an error.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7546
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7547 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7548 * Complete kill-region:: The function definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7549 * condition-case:: Dealing with a problem.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7550 * delete-and-extract-region:: Doing the work.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7551 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7552
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7553 @node Complete kill-region, condition-case, kill-region, kill-region
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7554 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7555 @unnumberedsubsec The Complete @code{kill-region} Definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7556 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7557
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7558 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7559 We will go through the @code{condition-case} code in a moment. First,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7560 let us look at the complete definition of @code{kill-region}, with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7561 comments added:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7562
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7563 @c v 21
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7564 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7565 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7566 (defun kill-region (beg end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7567 "Kill between point and mark.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7568 The text is deleted but saved in the kill ring."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7569 (interactive "r")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7570 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7571
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7572 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7573 ;; 1. `condition-case' takes three arguments.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7574 ;; If the first argument is nil, as it is here,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7575 ;; information about the error signal is not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7576 ;; stored for use by another function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7577 (condition-case nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7578 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7579
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7580 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7581 ;; 2. The second argument to `condition-case'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7582 ;; tells the Lisp interpreter what to do when all goes well.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7583 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7584
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7585 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7586 ;; The `delete-and-extract-region' function usually does the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7587 ;; work. If the beginning and ending of the region are both
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7588 ;; the same, then the variable `string' will be empty, or nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7589 (let ((string (delete-and-extract-region beg end)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7590 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7591
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7592 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7593 ;; `when' is an `if' clause that cannot take an `else-part'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7594 ;; Emacs normally sets the value of `last-command' to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7595 ;; previous command.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7596 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7597 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7598 ;; `kill-append' concatenates the new string and the old.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7599 ;; `kill-new' inserts text into a new item in the kill ring.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7600 (when string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7601 (if (eq last-command 'kill-region)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7602 ;; if true, prepend string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7603 (kill-append string (< end beg))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7604 (kill-new string)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7605 (setq this-command 'kill-region))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7606 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7607
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7608 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7609 ;; 3. The third argument to `condition-case' tells the interpreter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7610 ;; what to do with an error.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7611 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7612 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7613 ;; The third argument has a conditions part and a body part.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7614 ;; If the conditions are met (in this case,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7615 ;; if text or buffer is read-only)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7616 ;; then the body is executed.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7617 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7618 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7619 ((buffer-read-only text-read-only) ;; this is the if-part
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7620 ;; then...
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7621 (copy-region-as-kill beg end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7622 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7623 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7624 (if kill-read-only-ok ;; usually this variable is nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7625 (message "Read only text copied to kill ring")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7626 ;; or else, signal an error if the buffer is read-only;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7627 (barf-if-buffer-read-only)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7628 ;; and, in any case, signal that the text is read-only.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7629 (signal 'text-read-only (list (current-buffer)))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7630 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7631 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7632
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7633 @node condition-case, delete-and-extract-region, Complete kill-region, kill-region
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7634 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7635 @subsection @code{condition-case}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7636 @findex condition-case
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7637
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7638 As we have seen earlier (@pxref{Making Errors, , Generate an Error
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7639 Message}), when the Emacs Lisp interpreter has trouble evaluating an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7640 expression, it provides you with help; in the jargon, this is called
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7641 ``signaling an error''. Usually, the computer stops the program and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7642 shows you a message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7643
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7644 However, some programs undertake complicated actions. They should not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7645 simply stop on an error. In the @code{kill-region} function, the most
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7646 likely error is that you will try to kill text that is read-only and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7647 cannot be removed. So the @code{kill-region} function contains code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7648 to handle this circumstance. This code, which makes up the body of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7649 the @code{kill-region} function, is inside of a @code{condition-case}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7650 special form.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7651
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7652 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7653 The template for @code{condition-case} looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7654
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7655 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7656 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7657 (condition-case
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7658 @var{var}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7659 @var{bodyform}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7660 @var{error-handler}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7661 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7662 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7663
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7664 The second argument, @var{bodyform}, is straightforward. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7665 @code{condition-case} special form causes the Lisp interpreter to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7666 evaluate the code in @var{bodyform}. If no error occurs, the special
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7667 form returns the code's value and produces the side-effects, if any.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7668
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7669 In short, the @var{bodyform} part of a @code{condition-case}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7670 expression determines what should happen when everything works
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7671 correctly.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7672
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7673 However, if an error occurs, among its other actions, the function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7674 generating the error signal will define one or more error condition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7675 names.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7676
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7677 An error handler is the third argument to @code{condition case}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7678 An error handler has two parts, a @var{condition-name} and a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7679 @var{body}. If the @var{condition-name} part of an error handler
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7680 matches a condition name generated by an error, then the @var{body}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7681 part of the error handler is run.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7682
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7683 As you will expect, the @var{condition-name} part of an error handler
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7684 may be either a single condition name or a list of condition names.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7685
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7686 Also, a complete @code{condition-case} expression may contain more
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7687 than one error handler. When an error occurs, the first applicable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7688 handler is run.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7689
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7690 Lastly, the first argument to the @code{condition-case} expression,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7691 the @var{var} argument, is sometimes bound to a variable that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7692 contains information about the error. However, if that argument is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7693 nil, as is the case in @code{kill-region}, that information is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7694 discarded.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7695
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7696 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7697 In brief, in the @code{kill-region} function, the code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7698 @code{condition-case} works like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7699
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7700 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7701 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7702 @var{If no errors}, @var{run only this code}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7703 @var{but}, @var{if errors}, @var{run this other code}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7704 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7705 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7706
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7707 @node delete-and-extract-region, , condition-case, kill-region
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7708 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7709 @subsection @code{delete-and-extract-region}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7710 @findex delete-and-extract-region
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7711
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7712 A @code{condition-case} expression has two parts, a part that is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7713 evaluated in the expectation that all will go well, but which may
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7714 generate an error; and a part that is evaluated when there is an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7715 error.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7716
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7717 First, let us look at the code in @code{kill-region} that is run in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7718 the expectation that all goes well. This is the core of the function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7719 The code looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7720
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7721 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7722 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7723 (let ((string (delete-and-extract-region beg end)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7724 (when string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7725 (if (eq last-command 'kill-region)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7726 (kill-append string (< end beg))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7727 (kill-new string)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7728 (setq this-command 'kill-region))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7729 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7730 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7731
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7732 It looks complicated because we have the new functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7733 @code{delete-and-extract-region}, @code{kill-append}, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7734 @code{kill-new} as well as the new variables,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7735 @code{last-command} and @code{this-command}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7736
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7737 The @code{delete-and-extract-region} function is straightforward. It
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7738 is a built-in function that deletes the text in a region (a side
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7739 effect) and also returns that text. This is the function that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7740 actually removes the text. (And if it cannot do that, it signals the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7741 error.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7742
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7743 In this @code{let} expression, the text that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7744 @code{delete-and-extract-region} returns is placed in the local
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7745 variable called @samp{string}. This is the text that is removed from
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7746 the buffer. (To be more precise, the variable is set to point to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7747 address of the extracted text; to say it is `placed in' the variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7748 is simply a shorthand.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7749
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7750 If the variable @samp{string} does point to text, that text is added
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7751 to the kill ring. The variable will have a @code{nil} value if no
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7752 text was removed.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7753
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7754 The code uses @code{when} to determine whether the variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7755 @samp{string} points to text. A @code{when} statement is simply a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7756 programmers' convenience. A @code{when} statement is an @code{if}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7757 statement without the possibility of an else clause. In your mind, you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7758 can replace @code{when} with @code{if} and understand what goes on.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7759 That is what the Lisp interpreter does.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7760
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7761 @cindex Macro, lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7762 @cindex Lisp macro
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7763 Technically speaking, @code{when} is a Lisp macro. A Lisp @dfn{macro}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7764 enables you to define new control constructs and other language
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7765 features. It tells the interpreter how to compute another Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7766 expression which will in turn compute the value. In this case, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7767 `other expression' is an @code{if} expression. For more about Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7768 macros, see @ref{Macros, , Macros, elisp, The GNU Emacs Lisp Reference
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7769 Manual}. The C programming language also provides macros. These are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7770 different, but also useful. We will briefly look at C macros in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7771 @ref{Digression into C, , @code{delete-and-extract-region}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7772 Digressing into C}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7773
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7774 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7775 If the string has content, then another conditional expression is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7776 executed. This is an @code{if} with both a then-part and an else-part.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7777
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7778 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7779 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7780 (if (eq last-command 'kill-region)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7781 (kill-append string (< end beg))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7782 (kill-new string)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7783 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7784 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7785
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7786 The then-part is evaluated if the previous command was another call to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7787 @code{kill-region}; if not, the else-part is evaluated.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7788
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7789 @code{last-command} is a variable that comes with Emacs that we have
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7790 not seen before. Normally, whenever a function is executed, Emacs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7791 sets the value of @code{last-command} to the previous command.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7792
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7793 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7794 In this segment of the definition, the @code{if} expression checks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7795 whether the previous command was @code{kill-region}. If it was,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7796
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7797 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7798 (kill-append string (< end beg))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7799 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7801 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7802 concatenates a copy of the newly clipped text to the just previously
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7803 clipped text in the kill ring. (If the @w{@code{(< end beg))}}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7804 expression is true, @code{kill-append} prepends the string to the just
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7805 previously clipped text. For a detailed discussion, see
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7806 @ref{kill-append function, , The @code{kill-append} function}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7807
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7808 If you then yank back the text, i.e., `paste' it, you get both
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7809 pieces of text at once. That way, if you delete two words in a row,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7810 and then yank them back, you get both words, in their proper order,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7811 with one yank. (The @w{@code{(< end beg))}} expression makes sure the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7812 order is correct.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7813
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7814 On the other hand, if the previous command is not @code{kill-region},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7815 then the @code{kill-new} function is called, which adds the text to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7816 the kill ring as the latest item, and sets the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7817 @code{kill-ring-yank-pointer} variable to point to it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7818
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7819 @node Digression into C, defvar, kill-region, Cutting & Storing Text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7820 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7821 @section @code{delete-and-extract-region}: Digressing into C
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7822 @findex delete-and-extract-region
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7823 @cindex C, a digression into
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7824 @cindex Digression into C
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7825
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7826 The @code{zap-to-char} command uses the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7827 @code{delete-and-extract-region} function, which in turn uses two
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7828 other functions, @code{copy-region-as-kill} and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7829 @code{del_range_1}. The @code{copy-region-as-kill} function will be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7830 described in a following section; it puts a copy of the region in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7831 kill ring so it can be yanked back. (@xref{copy-region-as-kill, ,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7832 @code{copy-region-as-kill}}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7833
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7834 The @code{delete-and-extract-region} function removes the contents of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7835 a region and you cannot get them back.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7836
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7837 Unlike the other code discussed here, @code{delete-and-extract-region}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7838 is not written in Emacs Lisp; it is written in C and is one of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7839 primitives of the GNU Emacs system. Since it is very simple, I will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7840 digress briefly from Lisp and describe it here.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7841
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7842 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7843 Like many of the other Emacs primitives,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7844 @code{delete-and-extract-region} is written as an instance of a C
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7845 macro, a macro being a template for code. The complete macro looks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7846 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7847
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7848 @c /usr/local/src/emacs/src/editfns.c
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7849 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7850 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7851 DEFUN ("delete-and-extract-region", Fdelete_and_extract_region,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7852 Sdelete_and_extract_region, 2, 2, 0,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7853 "Delete the text between START and END and return it.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7854 (start, end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7855 Lisp_Object start, end;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7856 @{
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7857 validate_region (&start, &end);
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7858 return del_range_1 (XINT (start), XINT (end), 1, 1);
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7859 @}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7860 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7861 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7862
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7863 Without going into the details of the macro writing process, let me
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7864 point out that this macro starts with the word @code{DEFUN}. The word
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7865 @code{DEFUN} was chosen since the code serves the same purpose as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7866 @code{defun} does in Lisp. The word @code{DEFUN} is followed by seven
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7867 parts inside of parentheses:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7868
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7869 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7870 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7871 The first part is the name given to the function in Lisp,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7872 @code{delete-and-extract-region}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7873
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7874 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7875 The second part is the name of the function in C,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7876 @code{Fdelete_and_extract_region}. By convention, it starts with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7877 @samp{F}. Since C does not use hyphens in names, underscores are used
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7878 instead.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7879
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7880 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7881 The third part is the name for the C constant structure that records
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7882 information on this function for internal use. It is the name of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7883 function in C but begins with an @samp{S} instead of an @samp{F}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7884
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7885 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7886 The fourth and fifth parts specify the minimum and maximum number of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7887 arguments the function can have. This function demands exactly 2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7888 arguments.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7889
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7890 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7891 The sixth part is nearly like the argument that follows the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7892 @code{interactive} declaration in a function written in Lisp: a letter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7893 followed, perhaps, by a prompt. The only difference from the Lisp is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7894 when the macro is called with no arguments. Then you write a @code{0}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7895 (which is a `null string'), as in this macro.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7896
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7897 If you were to specify arguments, you would place them between
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7898 quotation marks. The C macro for @code{goto-char} includes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7899 @code{"NGoto char: "} in this position to indicate that the function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7900 expects a raw prefix, in this case, a numerical location in a buffer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7901 and provides a prompt.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7902
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7903 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7904 The seventh part is a documentation string, just like the one for a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7905 function written in Emacs Lisp, except that every newline must be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7906 written explicitly as @samp{\n} followed by a backslash and carriage
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7907 return.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7908
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7909 @need 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7910 Thus, the first two lines of documentation for @code{goto-char} are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7911 written like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7912
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7913 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7914 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7915 "Set point to POSITION, a number or marker.\n\
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7916 Beginning of buffer is position (point-min), end is (point-max).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7917 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7918 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7919 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7920
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7921 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7922 In a C macro, the formal parameters come next, with a statement of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7923 what kind of object they are, followed by what might be called the `body'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7924 of the macro. For @code{delete-and-extract-region} the `body'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7925 consists of the following two lines:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7926
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7927 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7928 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7929 validate_region (&start, &end);
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7930 return del_range_1 (XINT (start), XINT (end), 1, 1);
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7931 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7932 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7933
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7934 The first function, @code{validate_region} checks whether the values
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7935 passed as the beginning and end of the region are the proper type and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7936 are within range. The second function, @code{del_range_1}, actually
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7937 deletes the text.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7938
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7939 @code{del_range_1} is a complex function we will not look into. It
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7940 updates the buffer and does other things.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7941
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7942 However, it is worth looking at the two arguments passed to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7943 @code{del_range}. These are @w{@code{XINT (start)}} and @w{@code{XINT
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7944 (end)}}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7945
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7946 As far as the C language is concerned, @code{start} and @code{end} are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7947 two integers that mark the beginning and end of the region to be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7948 deleted@footnote{More precisely, and requiring more expert knowledge
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7949 to understand, the two integers are of type `Lisp_Object', which can
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7950 also be a C union instead of an integer type.}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7951
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7952 In early versions of Emacs, these two numbers were thirty-two bits
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7953 long, but the code is slowly being generalized to handle other
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7954 lengths. Three of the available bits are used to specify the type of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7955 information and a fourth bit is used for handling the computer's
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7956 memory; the remaining bits are used as `content'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7957
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7958 @samp{XINT} is a C macro that extracts the relevant number from the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7959 longer collection of bits; the four other bits are discarded.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7960
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7961 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7962 The command in @code{delete-and-extract-region} looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7963
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7964 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7965 del_range_1 (XINT (start), XINT (end), 1, 1);
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7966 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7967
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7968 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7969 It deletes the region between the beginning position, @code{start},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7970 and the ending position, @code{end}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7971
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7972 From the point of view of the person writing Lisp, Emacs is all very
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7973 simple; but hidden underneath is a great deal of complexity to make it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7974 all work.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7975
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7976 @node defvar, copy-region-as-kill, Digression into C, Cutting & Storing Text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7977 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7978 @section Initializing a Variable with @code{defvar}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7979 @findex defvar
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7980 @cindex Initializing a variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7981 @cindex Variable initialization
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7982
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7983 Unlike the @code{delete-and-extract-region} function, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7984 @code{copy-region-as-kill} function is written in Emacs Lisp. Two
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7985 functions within it, @code{kill-append} and @code{kill-new}, copy a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7986 region in a buffer and save it in a variable called the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7987 @code{kill-ring}. This section describes how the @code{kill-ring}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7988 variable is created and initialized using the @code{defvar} special
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7989 form.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7990
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7991 (Again we note that the term @code{kill-ring} is a misnomer. The text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7992 that is clipped out of the buffer can be brought back; it is not a ring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7993 of corpses, but a ring of resurrectable text.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7994
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7995 In Emacs Lisp, a variable such as the @code{kill-ring} is created and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7996 given an initial value by using the @code{defvar} special form. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7997 name comes from ``define variable''.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7998
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7999 The @code{defvar} special form is similar to @code{setq} in that it sets
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8000 the value of a variable. It is unlike @code{setq} in two ways: first,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8001 it only sets the value of the variable if the variable does not already
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8002 have a value. If the variable already has a value, @code{defvar} does
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8003 not override the existing value. Second, @code{defvar} has a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8004 documentation string.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8005
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8006 (Another special form, @code{defcustom}, is designed for variables
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8007 that people customize. It has more features than @code{defvar}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8008 (@xref{defcustom, , Setting Variables with @code{defcustom}}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8009
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8010 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8011 * See variable current value::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8012 * defvar and asterisk:: An old-time convention.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8013 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8014
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8015 @node See variable current value, defvar and asterisk, defvar, defvar
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8016 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8017 @unnumberedsubsec Seeing the Current Value of a Variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8018 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8019
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8020 You can see the current value of a variable, any variable, by using
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8021 the @code{describe-variable} function, which is usually invoked by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8022 typing @kbd{C-h v}. If you type @kbd{C-h v} and then @code{kill-ring}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8023 (followed by @key{RET}) when prompted, you will see what is in your
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8024 current kill ring---this may be quite a lot! Conversely, if you have
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8025 been doing nothing this Emacs session except read this document, you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8026 may have nothing in it. Also, you will see the documentation for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8027 @code{kill-ring}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8028
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8029 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8030 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8031 Documentation:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8032 List of killed text sequences.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8033 Since the kill ring is supposed to interact nicely with cut-and-paste
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8034 facilities offered by window systems, use of this variable should
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8035 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8036 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8037 interact nicely with `interprogram-cut-function' and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8038 `interprogram-paste-function'. The functions `kill-new',
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8039 `kill-append', and `current-kill' are supposed to implement this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8040 interaction; you may want to use them instead of manipulating the kill
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8041 ring directly.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8042 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8043 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8044
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8045 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8046 The kill ring is defined by a @code{defvar} in the following way:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8047
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8048 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8049 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8050 (defvar kill-ring nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8051 "List of killed text sequences.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8052 @dots{}")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8053 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8054 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8055
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8056 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8057 In this variable definition, the variable is given an initial value of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8058 @code{nil}, which makes sense, since if you have saved nothing, you want
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8059 nothing back if you give a @code{yank} command. The documentation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8060 string is written just like the documentation string of a @code{defun}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8061 As with the documentation string of the @code{defun}, the first line of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8062 the documentation should be a complete sentence, since some commands,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8063 like @code{apropos}, print only the first line of documentation.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8064 Succeeding lines should not be indented; otherwise they look odd when
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8065 you use @kbd{C-h v} (@code{describe-variable}).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8066
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8067 @node defvar and asterisk, , See variable current value, defvar
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8068 @subsection @code{defvar} and an asterisk
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8069 @findex defvar @r{for a user customizable variable}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8070 @findex defvar @r{with an asterisk}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8071
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8072 In the past, Emacs used the @code{defvar} special form both for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8073 internal variables that you would not expect a user to change and for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8074 variables that you do expect a user to change. Although you can still
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8075 use @code{defvar} for user customizable variables, please use
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8076 @code{defcustom} instead, since that special form provides a path into
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8077 the Customization commands. (@xref{defcustom, , Setting Variables
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8078 with @code{defcustom}}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8079
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8080 When you specified a variable using the @code{defvar} special form,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8081 you could distinguish a readily settable variable from others by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8082 typing an asterisk, @samp{*}, in the first column of its documentation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8083 string. For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8084
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8085 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8086 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8087 (defvar shell-command-default-error-buffer nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8088 "*Buffer name for `shell-command' @dots{} error output.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8089 @dots{} ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8090 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8091 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8092
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8093 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8094 This means that you could (and still can) use the @code{edit-options}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8095 command to change the value of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8096 @code{shell-command-default-error-buffer} temporarily.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8097
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8098 @findex edit-options
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8099 However, options set using @code{edit-options} are set only for the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8100 duration of your editing session. The new values are not saved
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8101 between sessions. Each time Emacs starts, it reads the original
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8102 value, unless you change the value within your @file{.emacs} file,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8103 either by setting it manually or by using @code{customize}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8104 @xref{Emacs Initialization, , Your @file{.emacs} File}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8105
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8106 For me, the major use of the @code{edit-options} command is to suggest
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8107 variables that I might want to set in my @file{.emacs} file. I urge
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8108 you to look through the list. (@xref{Edit Options, , Editing Variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8109 Values, emacs, The GNU Emacs Manual}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8110
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8111 @node copy-region-as-kill, cons & search-fwd Review, defvar, Cutting & Storing Text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8112 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8113 @section @code{copy-region-as-kill}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8114 @findex copy-region-as-kill
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8115 @findex nthcdr
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8116
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8117 The @code{copy-region-as-kill} function copies a region of text from a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8118 buffer and (via either @code{kill-append} or @code{kill-new}) saves it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8119 in the @code{kill-ring}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8120
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8121 If you call @code{copy-region-as-kill} immediately after a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8122 @code{kill-region} command, Emacs appends the newly copied text to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8123 previously copied text. This means that if you yank back the text, you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8124 get it all, from both this and the previous operation. On the other
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8125 hand, if some other command precedes the @code{copy-region-as-kill},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8126 the function copies the text into a separate entry in the kill ring.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8127
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8128 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8129 * Complete copy-region-as-kill:: The complete function definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8130 * copy-region-as-kill body:: The body of @code{copy-region-as-kill}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8131 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8132
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8133 @node Complete copy-region-as-kill, copy-region-as-kill body, copy-region-as-kill, copy-region-as-kill
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8134 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8135 @unnumberedsubsec The complete @code{copy-region-as-kill} function definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8136 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8137
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8138 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8139 Here is the complete text of the version 21 @code{copy-region-as-kill}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8140 function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8141
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8142 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8143 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8144 (defun copy-region-as-kill (beg end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8145 "Save the region as if killed, but don't kill it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8146 In Transient Mark mode, deactivate the mark.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8147 If `interprogram-cut-function' is non-nil, also save
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8148 the text for a window system cut and paste."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8149 (interactive "r")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8150 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8151 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8152 (if (eq last-command 'kill-region)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8153 (kill-append (buffer-substring beg end) (< end beg))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8154 (kill-new (buffer-substring beg end)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8155 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8156 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8157 (if transient-mark-mode
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8158 (setq deactivate-mark t))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8159 nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8160 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8161 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8162
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8163 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8164 As usual, this function can be divided into its component parts:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8165
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8166 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8167 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8168 (defun copy-region-as-kill (@var{argument-list})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8169 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8170 (interactive "r")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8171 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8172 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8173 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8174
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8175 The arguments are @code{beg} and @code{end} and the function is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8176 interactive with @code{"r"}, so the two arguments must refer to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8177 beginning and end of the region. If you have been reading though this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8178 document from the beginning, understanding these parts of a function is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8179 almost becoming routine.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8180
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8181 The documentation is somewhat confusing unless you remember that the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8182 word `kill' has a meaning different from its usual meaning. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8183 `Transient Mark' and @code{interprogram-cut-function} comments explain
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8184 certain side-effects.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8185
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8186 After you once set a mark, a buffer always contains a region. If you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8187 wish, you can use Transient Mark mode to highlight the region
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8188 temporarily. (No one wants to highlight the region all the time, so
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8189 Transient Mark mode highlights it only at appropriate times. Many
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8190 people turn off Transient Mark mode, so the region is never
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8191 highlighted.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8192
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8193 Also, a windowing system allows you to copy, cut, and paste among
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8194 different programs. In the X windowing system, for example, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8195 @code{interprogram-cut-function} function is @code{x-select-text},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8196 which works with the windowing system's equivalent of the Emacs kill
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8197 ring.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8198
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8199 The body of the @code{copy-region-as-kill} function starts with an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8200 @code{if} clause. What this clause does is distinguish between two
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8201 different situations: whether or not this command is executed
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8202 immediately after a previous @code{kill-region} command. In the first
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8203 case, the new region is appended to the previously copied text.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8204 Otherwise, it is inserted into the beginning of the kill ring as a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8205 separate piece of text from the previous piece.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8206
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8207 The last two lines of the function prevent the region from lighting up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8208 if Transient Mark mode is turned on.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8209
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8210 The body of @code{copy-region-as-kill} merits discussion in detail.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8211
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8212 @node copy-region-as-kill body, , Complete copy-region-as-kill, copy-region-as-kill
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8213 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8214 @subsection The Body of @code{copy-region-as-kill}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8215
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8216 The @code{copy-region-as-kill} function works in much the same way as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8217 the @code{kill-region} function (@pxref{kill-region,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8218 ,@code{kill-region}}). Both are written so that two or more kills in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8219 a row combine their text into a single entry. If you yank back the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8220 text from the kill ring, you get it all in one piece. Moreover, kills
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8221 that kill forward from the current position of the cursor are added to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8222 the end of the previously copied text and commands that copy text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8223 backwards add it to the beginning of the previously copied text. This
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8224 way, the words in the text stay in the proper order.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8225
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8226 Like @code{kill-region}, the @code{copy-region-as-kill} function makes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8227 use of the @code{last-command} variable that keeps track of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8228 previous Emacs command.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8229
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8230 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8231 * last-command & this-command::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8232 * kill-append function::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8233 * kill-new function::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8234 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8235
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8236 @node last-command & this-command, kill-append function, copy-region-as-kill body, copy-region-as-kill body
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8237 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8238 @unnumberedsubsubsec @code{last-command} and @code{this-command}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8239 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8240
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8241 Normally, whenever a function is executed, Emacs sets the value of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8242 @code{this-command} to the function being executed (which in this case
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8243 would be @code{copy-region-as-kill}). At the same time, Emacs sets
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8244 the value of @code{last-command} to the previous value of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8245 @code{this-command}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8246
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8247 In the first part of the body of the @code{copy-region-as-kill}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8248 function, an @code{if} expression determines whether the value of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8249 @code{last-command} is @code{kill-region}. If so, the then-part of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8250 the @code{if} expression is evaluated; it uses the @code{kill-append}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8251 function to concatenate the text copied at this call to the function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8252 with the text already in the first element (the @sc{car}) of the kill
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8253 ring. On the other hand, if the value of @code{last-command} is not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8254 @code{kill-region}, then the @code{copy-region-as-kill} function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8255 attaches a new element to the kill ring using the @code{kill-new}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8256 function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8257
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8258 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8259 The @code{if} expression reads as follows; it uses @code{eq}, which is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8260 a function we have not yet seen:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8261
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8262 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8263 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8264 (if (eq last-command 'kill-region)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8265 ;; @r{then-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8266 (kill-append (buffer-substring beg end) (< end beg))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8267 ;; @r{else-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8268 (kill-new (buffer-substring beg end)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8269 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8270 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8271
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8272 @findex eq @r{(example of use)}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8273 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8274 The @code{eq} function tests whether its first argument is the same Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8275 object as its second argument. The @code{eq} function is similar to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8276 @code{equal} function in that it is used to test for equality, but
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8277 differs in that it determines whether two representations are actually
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8278 the same object inside the computer, but with different names.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8279 @code{equal} determines whether the structure and contents of two
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8280 expressions are the same.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8281
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8282 If the previous command was @code{kill-region}, then the Emacs Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8283 interpreter calls the @code{kill-append} function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8284
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8285 @node kill-append function, kill-new function, last-command & this-command, copy-region-as-kill body
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8286 @unnumberedsubsubsec The @code{kill-append} function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8287 @findex kill-append
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8288
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8289 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8290 The @code{kill-append} function looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8291
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8292 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8293 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8294 (defun kill-append (string before-p)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8295 "Append STRING to the end of the latest kill in the kill ring.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8296 If BEFORE-P is non-nil, prepend STRING to the kill.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8297 If `interprogram-cut-function' is set, pass the resulting kill to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8298 it."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8299 (kill-new (if before-p
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8300 (concat string (car kill-ring))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8301 (concat (car kill-ring) string))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8302 t))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8303 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8304 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8305
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8306 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8307 The @code{kill-append} function is fairly straightforward. It uses
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8308 the @code{kill-new} function, which we will discuss in more detail in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8309 a moment.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8310
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8311 First, let us look at the conditional that is one of the two arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8312 to @code{kill-new}. It uses @code{concat} to concatenate the new text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8313 to the @sc{car} of the kill ring. Whether it prepends or appends the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8314 text depends on the results of an @code{if} expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8315
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8316 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8317 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8318 (if before-p ; @r{if-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8319 (concat string (car kill-ring)) ; @r{then-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8320 (concat (car kill-ring) string)) ; @r{else-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8321 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8322 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8323
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8324 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8325 If the region being killed is before the region that was killed in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8326 last command, then it should be prepended before the material that was
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8327 saved in the previous kill; and conversely, if the killed text follows
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8328 what was just killed, it should be appended after the previous text.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8329 The @code{if} expression depends on the predicate @code{before-p} to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8330 decide whether the newly saved text should be put before or after the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8331 previously saved text.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8332
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8333 The symbol @code{before-p} is the name of one of the arguments to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8334 @code{kill-append}. When the @code{kill-append} function is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8335 evaluated, it is bound to the value returned by evaluating the actual
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8336 argument. In this case, this is the expression @code{(< end beg)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8337 This expression does not directly determine whether the killed text in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8338 this command is located before or after the kill text of the last
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8339 command; what is does is determine whether the value of the variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8340 @code{end} is less than the value of the variable @code{beg}. If it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8341 is, it means that the user is most likely heading towards the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8342 beginning of the buffer. Also, the result of evaluating the predicate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8343 expression, @code{(< end beg)}, will be true and the text will be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8344 prepended before the previous text. On the other hand, if the value of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8345 the variable @code{end} is greater than the value of the variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8346 @code{beg}, the text will be appended after the previous text.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8347
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8348 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8349 When the newly saved text will be prepended, then the string with the new
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8350 text will be concatenated before the old text:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8351
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8352 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8353 (concat string (car kill-ring))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8354 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8355
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8356 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8357 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8358 But if the text will be appended, it will be concatenated
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8359 after the old text:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8360
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8361 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8362 (concat (car kill-ring) string))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8363 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8364
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8365 To understand how this works, we first need to review the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8366 @code{concat} function. The @code{concat} function links together or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8367 unites two strings of text. The result is a string. For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8368
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8369 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8370 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8371 (concat "abc" "def")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8372 @result{} "abcdef"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8373 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8374
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8375 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8376 (concat "new "
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8377 (car '("first element" "second element")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8378 @result{} "new first element"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8379
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8380 (concat (car
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8381 '("first element" "second element")) " modified")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8382 @result{} "first element modified"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8383 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8384 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8385
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8386 We can now make sense of @code{kill-append}: it modifies the contents
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8387 of the kill ring. The kill ring is a list, each element of which is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8388 saved text. The @code{kill-append} function uses the @code{kill-new}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8389 function which in turn uses the @code{setcar} function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8390
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8391 @node kill-new function, , kill-append function, copy-region-as-kill body
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8392 @unnumberedsubsubsec The @code{kill-new} function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8393 @findex kill-new
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8394
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8395 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8396 The @code{kill-new} function looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8397
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8398 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8399 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8400 (defun kill-new (string &optional replace)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8401 "Make STRING the latest kill in the kill ring.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8402 Set the kill-ring-yank pointer to point to it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8403 If `interprogram-cut-function' is non-nil, apply it to STRING.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8404 Optional second argument REPLACE non-nil means that STRING will replace
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8405 the front of the kill ring, rather than being added to the list."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8406 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8407 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8408 (and (fboundp 'menu-bar-update-yank-menu)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8409 (menu-bar-update-yank-menu string (and replace (car kill-ring))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8410 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8411 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8412 (if (and replace kill-ring)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8413 (setcar kill-ring string)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8414 (setq kill-ring (cons string kill-ring))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8415 (if (> (length kill-ring) kill-ring-max)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8416 (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8417 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8418 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8419 (setq kill-ring-yank-pointer kill-ring)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8420 (if interprogram-cut-function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8421 (funcall interprogram-cut-function string (not replace))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8422 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8423 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8424
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8425 As usual, we can look at this function in parts.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8426
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8427 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8428 The first line of the documentation makes sense:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8429
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8430 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8431 Make STRING the latest kill in the kill ring.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8432 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8433
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8434 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8435 Let's skip over the rest of the documentation for the moment.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8436
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8437 Also, let's skip over the first two lines of code, those involving
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8438 @code{menu-bar-update-yank-menu}. We will explain them below.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8439
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8440 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8441 The critical lines are these:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8442
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8443 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8444 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8445 (if (and replace kill-ring)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8446 ;; @r{then}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8447 (setcar kill-ring string)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8448 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8449 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8450 ;; @r{else}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8451 (setq kill-ring (cons string kill-ring))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8452 (if (> (length kill-ring) kill-ring-max)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8453 ;; @r{avoid overly long kill ring}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8454 (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8455 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8456 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8457 (setq kill-ring-yank-pointer kill-ring)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8458 (if interprogram-cut-function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8459 (funcall interprogram-cut-function string (not replace))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8460 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8461 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8462
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8463 The conditional test is @w{@code{(and replace kill-ring)}}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8464 This will be true when two conditions are met: the kill ring has
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8465 something in it, and the @code{replace} variable is true.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8466
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8467 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8468 The @code{kill-append} function sets @code{replace} to be true; then,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8469 when the kill ring has at least one item in it, the @code{setcar}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8470 expression is executed:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8471
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8472 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8473 (setcar kill-ring string)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8474 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8475
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8476 The @code{setcar} function actually changes the first element of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8477 @code{kill-ring} list to the value of @code{string}. It replaces the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8478 first element.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8479
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8480 On the other hand, if the kill ring is empty, or replace is false, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8481 else-part of the condition is executed:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8482
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8483 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8484 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8485 (setq kill-ring (cons string kill-ring))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8486 (if (> (length kill-ring) kill-ring-max)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8487 (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8488 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8489 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8490
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8491 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8492 This expression first constructs a new version of the kill ring by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8493 prepending @code{string} to the existing kill ring as a new element.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8494 Then it executes a second @code{if} clause. This second @code{if}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8495 clause keeps the kill ring from growing too long.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8496
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8497 Let's look at these two expressions in order.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8498
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8499 The @code{setq} line of the else-part sets the new value of the kill
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8500 ring to what results from adding the string being killed to the old kill
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8501 ring.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8502
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8503 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8504 We can see how this works with an example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8505
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8506 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8507 (setq example-list '("here is a clause" "another clause"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8508 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8509
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8510 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8511 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8512 After evaluating this expression with @kbd{C-x C-e}, you can evaluate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8513 @code{example-list} and see what it returns:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8514
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8515 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8516 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8517 example-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8518 @result{} ("here is a clause" "another clause")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8519 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8520 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8521
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8522 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8523 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8524 Now, we can add a new element on to this list by evaluating the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8525 following expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8526 @findex cons, @r{example}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8527
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8528 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8529 (setq example-list (cons "a third clause" example-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8530 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8531
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8532 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8533 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8534 When we evaluate @code{example-list}, we find its value is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8535
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8536 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8537 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8538 example-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8539 @result{} ("a third clause" "here is a clause" "another clause")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8540 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8541 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8542
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8543 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8544 Thus, the third clause was added to the list by @code{cons}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8545
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8546 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8547 This is exactly similar to what the @code{setq} and @code{cons} do in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8548 the function. Here is the line again:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8549
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8550 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8551 (setq kill-ring (cons string kill-ring))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8552 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8553
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8554 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8555 Now for the second part of the @code{if} clause. This expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8556 keeps the kill ring from growing too long. It looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8557
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8558 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8559 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8560 (if (> (length kill-ring) kill-ring-max)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8561 (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8562 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8563 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8564
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8565 The code checks whether the length of the kill ring is greater than
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8566 the maximum permitted length. This is the value of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8567 @code{kill-ring-max} (which is 60, by default). If the length of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8568 kill ring is too long, then this code sets the last element of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8569 kill ring to @code{nil}. It does this by using two functions,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8570 @code{nthcdr} and @code{setcdr}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8571
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8572 We looked at @code{setcdr} earlier (@pxref{setcdr, , @code{setcdr}}).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8573 It sets the @sc{cdr} of a list, just as @code{setcar} sets the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8574 @sc{car} of a list. In this case, however, @code{setcdr} will not be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8575 setting the @sc{cdr} of the whole kill ring; the @code{nthcdr}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8576 function is used to cause it to set the @sc{cdr} of the next to last
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8577 element of the kill ring---this means that since the @sc{cdr} of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8578 next to last element is the last element of the kill ring, it will set
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8579 the last element of the kill ring.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8580
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8581 @findex nthcdr, @r{example}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8582 The @code{nthcdr} function works by repeatedly taking the @sc{cdr} of a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8583 list---it takes the @sc{cdr} of the @sc{cdr} of the @sc{cdr}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8584 @dots{} It does this @var{N} times and returns the results.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8585
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8586 @findex setcdr, @r{example}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8587 Thus, if we had a four element list that was supposed to be three
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8588 elements long, we could set the @sc{cdr} of the next to last element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8589 to @code{nil}, and thereby shorten the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8590
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8591 You can see this by evaluating the following three expressions in turn.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8592 First set the value of @code{trees} to @code{(maple oak pine birch)},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8593 then set the @sc{cdr} of its second @sc{cdr} to @code{nil} and then
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8594 find the value of @code{trees}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8595
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8596 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8597 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8598 (setq trees '(maple oak pine birch))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8599 @result{} (maple oak pine birch)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8600 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8601
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8602 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8603 (setcdr (nthcdr 2 trees) nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8604 @result{} nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8605
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8606 trees
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8607 @result{} (maple oak pine)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8608 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8609 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8610
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8611 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8612 (The value returned by the @code{setcdr} expression is @code{nil} since
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8613 that is what the @sc{cdr} is set to.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8614
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8615 To repeat, in @code{kill-new}, the @code{nthcdr} function takes the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8616 @sc{cdr} a number of times that is one less than the maximum permitted
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8617 size of the kill ring and sets the @sc{cdr} of that element (which
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8618 will be the rest of the elements in the kill ring) to @code{nil}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8619 This prevents the kill ring from growing too long.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8620
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8621 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8622 The next to last expression in the @code{kill-new} function is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8623
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8624 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8625 (setq kill-ring-yank-pointer kill-ring)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8626 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8627
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8628 The @code{kill-ring-yank-pointer} is a global variable that is set to be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8629 the @code{kill-ring}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8630
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8631 Even though the @code{kill-ring-yank-pointer} is called a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8632 @samp{pointer}, it is a variable just like the kill ring. However, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8633 name has been chosen to help humans understand how the variable is used.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8634 The variable is used in functions such as @code{yank} and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8635 @code{yank-pop} (@pxref{Yanking, , Yanking Text Back}).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8636
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8637 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8638 Now, to return to the first two lines in the body of the function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8639
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8640 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8641 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8642 (and (fboundp 'menu-bar-update-yank-menu)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8643 (menu-bar-update-yank-menu string (and replace (car kill-ring))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8644 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8645 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8646
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8647 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8648 This is an expression whose first element is the function @code{and}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8649
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8650 @findex and, @r{introduced}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8651 The @code{and} special form evaluates each of its arguments until one of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8652 the arguments returns a value of @code{nil}, in which case the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8653 @code{and} expression returns @code{nil}; however, if none of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8654 arguments returns a value of @code{nil}, the value resulting from
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8655 evaluating the last argument is returned. (Since such a value is not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8656 @code{nil}, it is considered true in Emacs Lisp.) In other words, an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8657 @code{and} expression returns a true value only if all its arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8658 are true.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8659 @findex and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8660
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8661 In this case, the expression tests first to see whether
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8662 @code{menu-bar-update-yank-menu} exists as a function, and if so,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8663 calls it. The @code{fboundp} function returns true if the symbol it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8664 is testing has a function definition that `is not void'. If the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8665 symbol's function definition were void, we would receive an error
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8666 message, as we did when we created errors intentionally (@pxref{Making
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8667 Errors, , Generate an Error Message}).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8668
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8669 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8670 Essentially, the @code{and} is an @code{if} expression that reads like
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8671 this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8672
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8673 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8674 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8675 if @var{the-menu-bar-function-exists}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8676 then @var{execute-it}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8677 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8678 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8679
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8680 @code{menu-bar-update-yank-menu} is one of the functions that make it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8681 possible to use the `Select and Paste' menu in the Edit item of a menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8682 bar; using a mouse, you can look at the various pieces of text you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8683 have saved and select one piece to paste.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8684
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8685 Finally, the last expression in the @code{kill-new} function adds the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8686 newly copied string to whatever facility exists for copying and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8687 pasting among different programs running in a windowing system. In
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8688 the X Windowing system, for example, the @code{x-select-text} function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8689 takes the string and stores it in memory operated by X. You can paste
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8690 the string in another program, such as an Xterm.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8691
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8692 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8693 The expression looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8694
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8695 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8696 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8697 (if interprogram-cut-function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8698 (funcall interprogram-cut-function string (not replace))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8699 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8700 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8701
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8702 If an @code{interprogram-cut-function} exists, then Emacs executes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8703 @code{funcall}, which in turn calls its first argument as a function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8704 and passes the remaining arguments to it. (Incidentally, as far as I
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8705 can see, this @code{if} expression could be replaced by an @code{and}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8706 expression similar to the one in the first part of the function.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8707
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8708 We are not going to discuss windowing systems and other programs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8709 further, but merely note that this is a mechanism that enables GNU
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8710 Emacs to work easily and well with other programs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8711
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8712 This code for placing text in the kill ring, either concatenated with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8713 an existing element or as a new element, leads us to the code for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8714 bringing back text that has been cut out of the buffer---the yank
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8715 commands. However, before discussing the yank commands, it is better
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8716 to learn how lists are implemented in a computer. This will make
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8717 clear such mysteries as the use of the term `pointer'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8718
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8719 @node cons & search-fwd Review, search Exercises, copy-region-as-kill, Cutting & Storing Text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8720 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8721 @section Review
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8722
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8723 Here is a brief summary of some recently introduced functions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8724
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8725 @table @code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8726 @item car
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8727 @itemx cdr
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8728 @code{car} returns the first element of a list; @code{cdr} returns the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8729 second and subsequent elements of a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8730
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8731 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8732 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8733
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8734 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8735 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8736 (car '(1 2 3 4 5 6 7))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8737 @result{} 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8738 (cdr '(1 2 3 4 5 6 7))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8739 @result{} (2 3 4 5 6 7)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8740 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8741 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8742
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8743 @item cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8744 @code{cons} constructs a list by prepending its first argument to its
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8745 second argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8746
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8747 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8748 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8749
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8750 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8751 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8752 (cons 1 '(2 3 4))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8753 @result{} (1 2 3 4)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8754 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8755 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8756
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8757 @item nthcdr
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8758 Return the result of taking @sc{cdr} `n' times on a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8759 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8760 The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8761 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8762 $n^{th}$
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8763 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8764 @code{cdr}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8765 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8766 The `rest of the rest', as it were.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8767
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8768 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8769 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8770
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8771 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8772 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8773 (nthcdr 3 '(1 2 3 4 5 6 7))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8774 @result{} (4 5 6 7)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8775 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8776 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8777
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8778 @item setcar
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8779 @itemx setcdr
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8780 @code{setcar} changes the first element of a list; @code{setcdr}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8781 changes the second and subsequent elements of a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8782
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8783 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8784 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8785
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8786 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8787 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8788 (setq triple '(1 2 3))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8789
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8790 (setcar triple '37)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8791
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8792 triple
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8793 @result{} (37 2 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8794
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8795 (setcdr triple '("foo" "bar"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8796
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8797 triple
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8798 @result{} (37 "foo" "bar")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8799 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8800 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8801
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8802 @item progn
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8803 Evaluate each argument in sequence and then return the value of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8804 last.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8805
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8806 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8807 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8808
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8809 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8810 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8811 (progn 1 2 3 4)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8812 @result{} 4
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8813 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8814 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8815
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8816 @item save-restriction
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8817 Record whatever narrowing is in effect in the current buffer, if any,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8818 and restore that narrowing after evaluating the arguments.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8819
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8820 @item search-forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8821 Search for a string, and if the string is found, move point.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8822
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8823 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8824 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8825 Takes four arguments:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8826
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8827 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8828 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8829 The string to search for.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8830
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8831 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8832 Optionally, the limit of the search.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8833
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8834 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8835 Optionally, what to do if the search fails, return @code{nil} or an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8836 error message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8837
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8838 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8839 Optionally, how many times to repeat the search; if negative, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8840 search goes backwards.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8841 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8842
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8843 @item kill-region
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8844 @itemx delete-region
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8845 @itemx copy-region-as-kill
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8846
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8847 @code{kill-region} cuts the text between point and mark from the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8848 buffer and stores that text in the kill ring, so you can get it back
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8849 by yanking.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8850
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8851 @code{delete-and-extract-region} removes the text between point and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8852 mark from the buffer and throws it away. You cannot get it back.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8853
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8854 @code{copy-region-as-kill} copies the text between point and mark into
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8855 the kill ring, from which you can get it by yanking. The function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8856 does not cut or remove the text from the buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8857 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8858
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8859 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8860 @node search Exercises, , cons & search-fwd Review, Cutting & Storing Text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8861 @section Searching Exercises
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8862
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8863 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8864 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8865 Write an interactive function that searches for a string. If the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8866 search finds the string, leave point after it and display a message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8867 that says ``Found!''. (Do not use @code{search-forward} for the name
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8868 of this function; if you do, you will overwrite the existing version of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8869 @code{search-forward} that comes with Emacs. Use a name such as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8870 @code{test-search} instead.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8871
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8872 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8873 Write a function that prints the third element of the kill ring in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8874 echo area, if any; if the kill ring does not contain a third element,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8875 print an appropriate message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8876 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8877
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8878 @node List Implementation, Yanking, Cutting & Storing Text, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8879 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8880 @chapter How Lists are Implemented
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8881 @cindex Lists in a computer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8882
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8883 In Lisp, atoms are recorded in a straightforward fashion; if the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8884 implementation is not straightforward in practice, it is, nonetheless,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8885 straightforward in theory. The atom @samp{rose}, for example, is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8886 recorded as the four contiguous letters @samp{r}, @samp{o}, @samp{s},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8887 @samp{e}. A list, on the other hand, is kept differently. The mechanism
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8888 is equally simple, but it takes a moment to get used to the idea. A
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8889 list is kept using a series of pairs of pointers. In the series, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8890 first pointer in each pair points to an atom or to another list, and the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8891 second pointer in each pair points to the next pair, or to the symbol
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8892 @code{nil}, which marks the end of the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8893
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8894 A pointer itself is quite simply the electronic address of what is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8895 pointed to. Hence, a list is kept as a series of electronic addresses.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8896
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8897 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8898 * Lists diagrammed::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8899 * Symbols as Chest:: Exploring a powerful metaphor.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8900 * List Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8901 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8902
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8903 @node Lists diagrammed, Symbols as Chest, List Implementation, List Implementation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8904 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8905 @unnumberedsec Lists diagrammed
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8906 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8907
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8908 For example, the list @code{(rose violet buttercup)} has three elements,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8909 @samp{rose}, @samp{violet}, and @samp{buttercup}. In the computer, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8910 electronic address of @samp{rose} is recorded in a segment of computer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8911 memory along with the address that gives the electronic address of where
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8912 the atom @samp{violet} is located; and that address (the one that tells
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8913 where @samp{violet} is located) is kept along with an address that tells
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8914 where the address for the atom @samp{buttercup} is located.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8915
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8916 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8917 This sounds more complicated than it is and is easier seen in a diagram:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8918
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8919 @c clear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8920 @c !!! cons-cell-diagram #1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8921 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8922 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8923 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8924 ___ ___ ___ ___ ___ ___
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8925 |___|___|--> |___|___|--> |___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8926 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8927 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8928 --> rose --> violet --> buttercup
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8929 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8930 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8931 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8932 @ifset print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8933 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8934 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8935 @image{cons-1}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8936 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8937 % \input /usr/local/lib/tex/inputs/psfig.tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8938 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-1.eps}}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8939 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8940 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8941 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8942 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8943 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8944 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8945 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8946 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8947 ___ ___ ___ ___ ___ ___
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8948 |___|___|--> |___|___|--> |___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8949 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8950 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8951 --> rose --> violet --> buttercup
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8952 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8953 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8954 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8955 @end ifclear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8956
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8957 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8958 In the diagram, each box represents a word of computer memory that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8959 holds a Lisp object, usually in the form of a memory address. The boxes,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8960 i.e.@: the addresses, are in pairs. Each arrow points to what the address
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8961 is the address of, either an atom or another pair of addresses. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8962 first box is the electronic address of @samp{rose} and the arrow points
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8963 to @samp{rose}; the second box is the address of the next pair of boxes,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8964 the first part of which is the address of @samp{violet} and the second
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8965 part of which is the address of the next pair. The very last box
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8966 points to the symbol @code{nil}, which marks the end of the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8967
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8968 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8969 When a variable is set to a list with a function such as @code{setq},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8970 it stores the address of the first box in the variable. Thus,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8971 evaluation of the expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8972
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8973 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8974 (setq bouquet '(rose violet buttercup))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8975 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8976
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8977 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8978 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8979 creates a situation like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8980
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8981 @c cons-cell-diagram #2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8982 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8983 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8984 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8985 bouquet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8986 |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8987 | ___ ___ ___ ___ ___ ___
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8988 --> |___|___|--> |___|___|--> |___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8989 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8990 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8991 --> rose --> violet --> buttercup
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8992 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8993 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8994 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8995 @ifset print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8996 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8997 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8998 @image{cons-2}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8999 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9000 % \input /usr/local/lib/tex/inputs/psfig.tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9001 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-2.eps}}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9002 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9003 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9004 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9005 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9006 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9007 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9008 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9009 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9010 bouquet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9011 |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9012 | ___ ___ ___ ___ ___ ___
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9013 --> |___|___|--> |___|___|--> |___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9014 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9015 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9016 --> rose --> violet --> buttercup
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9017 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9018 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9019 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9020 @end ifclear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9021
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9022 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9023 In this example, the symbol @code{bouquet} holds the address of the first
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9024 pair of boxes.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9025
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9026 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9027 This same list can be illustrated in a different sort of box notation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9028 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9029
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9030 @c cons-cell-diagram #2a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9031 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9032 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9033 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9034 bouquet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9035 |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9036 | -------------- --------------- ----------------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9037 | | car | cdr | | car | cdr | | car | cdr |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9038 -->| rose | o------->| violet | o------->| butter- | nil |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9039 | | | | | | | cup | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9040 -------------- --------------- ----------------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9041 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9042 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9043 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9044 @ifset print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9045 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9046 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9047 @image{cons-2a}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9048 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9049 % \input /usr/local/lib/tex/inputs/psfig.tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9050 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-2a.eps}}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9051 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9052 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9053 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9054 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9055 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9056 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9057 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9058 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9059 bouquet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9060 |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9061 | -------------- --------------- ----------------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9062 | | car | cdr | | car | cdr | | car | cdr |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9063 -->| rose | o------->| violet | o------->| butter- | nil |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9064 | | | | | | | cup | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9065 -------------- --------------- ----------------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9066 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9067 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9068 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9069 @end ifclear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9070
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9071 (Symbols consist of more than pairs of addresses, but the structure of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9072 a symbol is made up of addresses. Indeed, the symbol @code{bouquet}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9073 consists of a group of address-boxes, one of which is the address of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9074 the printed word @samp{bouquet}, a second of which is the address of a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9075 function definition attached to the symbol, if any, a third of which
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9076 is the address of the first pair of address-boxes for the list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9077 @code{(rose violet buttercup)}, and so on. Here we are showing that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9078 the symbol's third address-box points to the first pair of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9079 address-boxes for the list.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9080
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9081 If a symbol is set to the @sc{cdr} of a list, the list itself is not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9082 changed; the symbol simply has an address further down the list. (In
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9083 the jargon, @sc{car} and @sc{cdr} are `non-destructive'.) Thus,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9084 evaluation of the following expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9085
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9086 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9087 (setq flowers (cdr bouquet))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9088 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9089
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9090 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9091 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9092 produces this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9093
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9094 @c cons-cell-diagram #3
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9095 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9096 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9097 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9098 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9099 bouquet flowers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9100 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9101 | ___ ___ | ___ ___ ___ ___
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9102 --> | | | --> | | | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9103 |___|___|----> |___|___|--> |___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9104 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9105 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9106 --> rose --> violet --> buttercup
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9107 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9108 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9109 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9110 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9111 @ifset print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9112 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9113 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9114 @image{cons-3}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9115 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9116 % \input /usr/local/lib/tex/inputs/psfig.tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9117 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-3.eps}}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9118 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9119 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9120 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9121 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9122 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9123 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9124 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9125 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9126 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9127 bouquet flowers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9128 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9129 | ___ ___ | ___ ___ ___ ___
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9130 --> | | | --> | | | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9131 |___|___|----> |___|___|--> |___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9132 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9133 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9134 --> rose --> violet --> buttercup
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9135 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9136 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9137 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9138 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9139 @end ifclear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9140
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9141 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9142 The value of @code{flowers} is @code{(violet buttercup)}, which is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9143 to say, the symbol @code{flowers} holds the address of the pair of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9144 address-boxes, the first of which holds the address of @code{violet},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9145 and the second of which holds the address of @code{buttercup}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9146
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9147 A pair of address-boxes is called a @dfn{cons cell} or @dfn{dotted
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9148 pair}. @xref{List Type, , List Type , elisp, The GNU Emacs Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9149 Reference Manual}, and @ref{Dotted Pair Notation, , Dotted Pair
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9150 Notation, elisp, The GNU Emacs Lisp Reference Manual}, for more
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9151 information about cons cells and dotted pairs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9152
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9153 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9154 The function @code{cons} adds a new pair of addresses to the front of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9155 a series of addresses like that shown above. For example, evaluating
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9156 the expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9157
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9158 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9159 (setq bouquet (cons 'lily bouquet))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9160 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9161
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9162 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9163 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9164 produces:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9165
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9166 @c cons-cell-diagram #4
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9167 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9168 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9169 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9170 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9171 bouquet flowers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9172 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9173 | ___ ___ ___ ___ | ___ ___ ___ ___
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9174 --> | | | | | | --> | | | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9175 |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9176 | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9177 | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9178 --> lily --> rose --> violet --> buttercup
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9179 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9180 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9181 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9182 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9183 @ifset print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9184 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9185 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9186 @image{cons-4}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9187 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9188 % \input /usr/local/lib/tex/inputs/psfig.tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9189 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-4.eps}}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9190 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9191 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9192 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9193 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9194 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9195 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9196 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9197 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9198 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9199 bouquet flowers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9200 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9201 | ___ ___ ___ ___ | ___ ___ ___ ___
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9202 --> | | | | | | --> | | | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9203 |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9204 | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9205 | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9206 --> lily --> rose --> violet --> buttercup
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9207 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9208 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9209 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9210 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9211 @end ifclear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9212
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9213 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9214 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9215 However, this does not change the value of the symbol
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9216 @code{flowers}, as you can see by evaluating the following,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9217
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9218 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9219 (eq (cdr (cdr bouquet)) flowers)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9220 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9221
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9222 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9223 which returns @code{t} for true.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9224
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9225 Until it is reset, @code{flowers} still has the value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9226 @code{(violet buttercup)}; that is, it has the address of the cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9227 cell whose first address is of @code{violet}. Also, this does not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9228 alter any of the pre-existing cons cells; they are all still there.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9229
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9230 Thus, in Lisp, to get the @sc{cdr} of a list, you just get the address
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9231 of the next cons cell in the series; to get the @sc{car} of a list,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9232 you get the address of the first element of the list; to @code{cons} a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9233 new element on a list, you add a new cons cell to the front of the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9234 That is all there is to it! The underlying structure of Lisp is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9235 brilliantly simple!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9236
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9237 And what does the last address in a series of cons cells refer to? It
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9238 is the address of the empty list, of @code{nil}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9239
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9240 In summary, when a Lisp variable is set to a value, it is provided with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9241 the address of the list to which the variable refers.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9242
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9243 @node Symbols as Chest, List Exercise, Lists diagrammed, List Implementation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9244 @section Symbols as a Chest of Drawers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9245 @cindex Symbols as a Chest of Drawers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9246 @cindex Chest of Drawers, metaphor for a symbol
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9247 @cindex Drawers, Chest of, metaphor for a symbol
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9248
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9249 In an earlier section, I suggested that you might imagine a symbol as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9250 being a chest of drawers. The function definition is put in one
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9251 drawer, the value in another, and so on. What is put in the drawer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9252 holding the value can be changed without affecting the contents of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9253 drawer holding the function definition, and vice-versa.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9254
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9255 Actually, what is put in each drawer is the address of the value or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9256 function definition. It is as if you found an old chest in the attic,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9257 and in one of its drawers you found a map giving you directions to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9258 where the buried treasure lies.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9259
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9260 (In addition to its name, symbol definition, and variable value, a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9261 symbol has a `drawer' for a @dfn{property list} which can be used to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9262 record other information. Property lists are not discussed here; see
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9263 @ref{Property Lists, , Property Lists, elisp, The GNU Emacs Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9264 Reference Manual}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9265
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9266 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9267 Here is a fanciful representation:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9268
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9269 @c chest-of-drawers diagram
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9270 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9271 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9272 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9273 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9274 Chest of Drawers Contents of Drawers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9275
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9276 __ o0O0o __
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9277 / \
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9278 ---------------------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9279 | directions to | [map to]
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9280 | symbol name | bouquet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9281 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9282 +---------------------+
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9283 | directions to |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9284 | symbol definition | [none]
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9285 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9286 +---------------------+
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9287 | directions to | [map to]
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9288 | variable value | (rose violet buttercup)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9289 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9290 +---------------------+
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9291 | directions to |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9292 | property list | [not described here]
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9293 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9294 +---------------------+
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9295 |/ \|
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9296 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9297 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9298 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9299 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9300 @ifset print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9301 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9302 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9303 @image{drawers}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9304 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9305 % \input /usr/local/lib/tex/inputs/psfig.tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9306 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/drawers.eps}}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9307 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9308 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9309 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9310 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9311 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9312 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9313 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9314 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9315 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9316 Chest of Drawers Contents of Drawers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9317
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9318 __ o0O0o __
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9319 / \
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9320 ---------------------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9321 | directions to | [map to]
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9322 | symbol name | bouquet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9323 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9324 +---------------------+
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9325 | directions to |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9326 | symbol definition | [none]
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9327 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9328 +---------------------+
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9329 | directions to | [map to]
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9330 | variable value | (rose violet buttercup)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9331 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9332 +---------------------+
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9333 | directions to |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9334 | property list | [not described here]
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9335 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9336 +---------------------+
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9337 |/ \|
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9338 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9339 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9340 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9341 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9342 @end ifclear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9343
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9344 @node List Exercise, , Symbols as Chest, List Implementation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9345 @section Exercise
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9346
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9347 Set @code{flowers} to @code{violet} and @code{buttercup}. Cons two
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9348 more flowers on to this list and set this new list to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9349 @code{more-flowers}. Set the @sc{car} of @code{flowers} to a fish.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9350 What does the @code{more-flowers} list now contain?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9351
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9352 @node Yanking, Loops & Recursion, List Implementation, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9353 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9354 @chapter Yanking Text Back
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9355 @findex yank
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9356 @findex rotate-yank-pointer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9357 @cindex Text retrieval
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9358 @cindex Retrieving text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9359 @cindex Pasting text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9360
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9361 Whenever you cut text out of a buffer with a `kill' command in GNU Emacs,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9362 you can bring it back with a `yank' command. The text that is cut out of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9363 the buffer is put in the kill ring and the yank commands insert the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9364 appropriate contents of the kill ring back into a buffer (not necessarily
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9365 the original buffer).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9366
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9367 A simple @kbd{C-y} (@code{yank}) command inserts the first item from
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9368 the kill ring into the current buffer. If the @kbd{C-y} command is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9369 followed immediately by @kbd{M-y}, the first element is replaced by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9370 the second element. Successive @kbd{M-y} commands replace the second
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9371 element with the third, fourth, or fifth element, and so on. When the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9372 last element in the kill ring is reached, it is replaced by the first
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9373 element and the cycle is repeated. (Thus the kill ring is called a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9374 `ring' rather than just a `list'. However, the actual data structure
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9375 that holds the text is a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9376 @xref{Kill Ring, , Handling the Kill Ring}, for the details of how the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9377 list is handled as a ring.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9378
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9379 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9380 * Kill Ring Overview:: The kill ring is a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9381 * kill-ring-yank-pointer:: The @code{kill-ring-yank-pointer} variable.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9382 * yank nthcdr Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9383 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9384
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9385 @node Kill Ring Overview, kill-ring-yank-pointer, Yanking, Yanking
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9386 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9387 @section Kill Ring Overview
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9388 @cindex Kill ring overview
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9389
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9390 The kill ring is a list of textual strings. This is what it looks like:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9391
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9392 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9393 ("some text" "a different piece of text" "yet more text")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9394 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9395
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9396 If this were the contents of my kill ring and I pressed @kbd{C-y}, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9397 string of characters saying @samp{some text} would be inserted in this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9398 buffer where my cursor is located.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9399
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9400 The @code{yank} command is also used for duplicating text by copying it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9401 The copied text is not cut from the buffer, but a copy of it is put on the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9402 kill ring and is inserted by yanking it back.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9403
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9404 Three functions are used for bringing text back from the kill ring:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9405 @code{yank}, which is usually bound to @kbd{C-y}; @code{yank-pop},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9406 which is usually bound to @kbd{M-y}; and @code{rotate-yank-pointer},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9407 which is used by the two other functions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9408
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9409 These functions refer to the kill ring through a variable called the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9410 @code{kill-ring-yank-pointer}. Indeed, the insertion code for both the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9411 @code{yank} and @code{yank-pop} functions is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9412
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9413 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9414 (insert (car kill-ring-yank-pointer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9415 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9416
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9417 To begin to understand how @code{yank} and @code{yank-pop} work, it is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9418 first necessary to look at the @code{kill-ring-yank-pointer} variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9419 and the @code{rotate-yank-pointer} function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9420
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9421 @node kill-ring-yank-pointer, yank nthcdr Exercises, Kill Ring Overview, Yanking
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9422 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9423 @section The @code{kill-ring-yank-pointer} Variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9424
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9425 @code{kill-ring-yank-pointer} is a variable, just as @code{kill-ring} is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9426 a variable. It points to something by being bound to the value of what
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9427 it points to, like any other Lisp variable.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9428
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9429 @need 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9430 Thus, if the value of the kill ring is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9431
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9432 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9433 ("some text" "a different piece of text" "yet more text")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9434 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9435
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9436 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9437 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9438 and the @code{kill-ring-yank-pointer} points to the second clause, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9439 value of @code{kill-ring-yank-pointer} is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9440
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9441 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9442 ("a different piece of text" "yet more text")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9443 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9444
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9445 As explained in the previous chapter (@pxref{List Implementation}), the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9446 computer does not keep two different copies of the text being pointed to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9447 by both the @code{kill-ring} and the @code{kill-ring-yank-pointer}. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9448 words ``a different piece of text'' and ``yet more text'' are not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9449 duplicated. Instead, the two Lisp variables point to the same pieces of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9450 text. Here is a diagram:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9451
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9452 @c cons-cell-diagram #5
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9453 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9454 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9455 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9456 kill-ring kill-ring-yank-pointer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9457 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9458 | ___ ___ | ___ ___ ___ ___
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9459 ---> | | | --> | | | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9460 |___|___|----> |___|___|--> |___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9461 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9462 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9463 | | --> "yet more text"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9464 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9465 | --> "a different piece of text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9466 |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9467 --> "some text"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9468 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9469 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9470 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9471 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9472 @ifset print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9473 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9474 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9475 @image{cons-5}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9476 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9477 % \input /usr/local/lib/tex/inputs/psfig.tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9478 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-5.eps}}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9479 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9480 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9481 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9482 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9483 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9484 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9485 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9486 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9487 kill-ring kill-ring-yank-pointer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9488 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9489 | ___ ___ | ___ ___ ___ ___
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9490 ---> | | | --> | | | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9491 |___|___|----> |___|___|--> |___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9492 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9493 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9494 | | --> "yet more text"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9495 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9496 | --> "a different piece of text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9497 |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9498 --> "some text"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9499 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9500 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9501 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9502 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9503 @end ifclear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9504
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9505 Both the variable @code{kill-ring} and the variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9506 @code{kill-ring-yank-pointer} are pointers. But the kill ring itself is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9507 usually described as if it were actually what it is composed of. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9508 @code{kill-ring} is spoken of as if it were the list rather than that it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9509 points to the list. Conversely, the @code{kill-ring-yank-pointer} is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9510 spoken of as pointing to a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9511
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9512 These two ways of talking about the same thing sound confusing at first but
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9513 make sense on reflection. The kill ring is generally thought of as the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9514 complete structure of data that holds the information of what has recently
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9515 been cut out of the Emacs buffers. The @code{kill-ring-yank-pointer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9516 on the other hand, serves to indicate---that is, to `point to'---that part
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9517 of the kill ring of which the first element (the @sc{car}) will be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9518 inserted.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9519
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9520 The @code{rotate-yank-pointer} function changes the element in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9521 kill ring to which the @code{kill-ring-yank-pointer} points; when the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9522 pointer is set to point to the next element beyond the end of the kill
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9523 ring, it automatically sets it to point to the first element of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9524 kill ring. This is how the list is transformed into a ring. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9525 @code{rotate-yank-pointer} function itself is not difficult, but
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9526 contains many details. It and the much simpler @code{yank} and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9527 @code{yank-pop} functions are described in an appendix.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9528 @xref{Kill Ring, , Handling the Kill Ring}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9529
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9530 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9531 @node yank nthcdr Exercises, , kill-ring-yank-pointer, Yanking
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9532 @section Exercises with @code{yank} and @code{nthcdr}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9533
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9534 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9535 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9536 Using @kbd{C-h v} (@code{describe-variable}), look at the value of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9537 your kill ring. Add several items to your kill ring; look at its
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9538 value again. Using @kbd{M-y} (@code{yank-pop)}, move all the way
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9539 around the kill ring. How many items were in your kill ring? Find
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9540 the value of @code{kill-ring-max}. Was your kill ring full, or could
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9541 you have kept more blocks of text within it?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9542
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9543 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9544 Using @code{nthcdr} and @code{car}, construct a series of expressions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9545 to return the first, second, third, and fourth elements of a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9546 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9547
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9548 @node Loops & Recursion, Regexp Search, Yanking, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9549 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9550 @chapter Loops and Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9551 @cindex Loops and recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9552 @cindex Recursion and loops
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9553 @cindex Repetition (loops)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9554
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9555 Emacs Lisp has two primary ways to cause an expression, or a series of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9556 expressions, to be evaluated repeatedly: one uses a @code{while}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9557 loop, and the other uses @dfn{recursion}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9558
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9559 Repetition can be very valuable. For example, to move forward four
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9560 sentences, you need only write a program that will move forward one
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9561 sentence and then repeat the process four times. Since a computer does
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9562 not get bored or tired, such repetitive action does not have the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9563 deleterious effects that excessive or the wrong kinds of repetition can
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9564 have on humans.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9565
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9566 People mostly write Emacs Lisp functions using @code{while} loops and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9567 their kin; but you can use recursion, which provides a very powerful
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9568 way to think about and then to solve problems@footnote{You can write
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9569 recursive functions to be frugal or wasteful of mental or computer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9570 resources; as it happens, methods that people find easy---that are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9571 frugal of `mental resources'---sometimes use considerable computer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9572 resources. Emacs was designed to run on machines that we now consider
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9573 limited and its default settings are conservative. You may want to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9574 increase the values of @code{max-specpdl-size} and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9575 @code{max-lisp-eval-depth}. In my @file{.emacs} file, I set them to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9576 15 and 30 times their default value.}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9577
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9578 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9579 * while:: Causing a stretch of code to repeat.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9580 * dolist dotimes::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9581 * Recursion:: Causing a function to call itself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9582 * Looping exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9583 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9584
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9585 @node while, dolist dotimes, Loops & Recursion, Loops & Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9586 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9587 @section @code{while}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9588 @cindex Loops
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9589 @findex while
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9590
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9591 The @code{while} special form tests whether the value returned by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9592 evaluating its first argument is true or false. This is similar to what
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9593 the Lisp interpreter does with an @code{if}; what the interpreter does
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9594 next, however, is different.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9595
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9596 In a @code{while} expression, if the value returned by evaluating the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9597 first argument is false, the Lisp interpreter skips the rest of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9598 expression (the @dfn{body} of the expression) and does not evaluate it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9599 However, if the value is true, the Lisp interpreter evaluates the body
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9600 of the expression and then again tests whether the first argument to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9601 @code{while} is true or false. If the value returned by evaluating the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9602 first argument is again true, the Lisp interpreter again evaluates the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9603 body of the expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9604
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9605 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9606 The template for a @code{while} expression looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9607
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9608 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9609 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9610 (while @var{true-or-false-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9611 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9612 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9613 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9614
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9615 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9616 * Looping with while:: Repeat so long as test returns true.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9617 * Loop Example:: A @code{while} loop that uses a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9618 * print-elements-of-list:: Uses @code{while}, @code{car}, @code{cdr}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9619 * Incrementing Loop:: A loop with an incrementing counter.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9620 * Decrementing Loop:: A loop with a decrementing counter.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9621 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9622
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9623 @node Looping with while, Loop Example, while, while
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9624 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9625 @unnumberedsubsec Looping with @code{while}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9626 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9627
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9628 So long as the true-or-false-test of the @code{while} expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9629 returns a true value when it is evaluated, the body is repeatedly
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9630 evaluated. This process is called a loop since the Lisp interpreter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9631 repeats the same thing again and again, like an airplane doing a loop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9632 When the result of evaluating the true-or-false-test is false, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9633 Lisp interpreter does not evaluate the rest of the @code{while}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9634 expression and `exits the loop'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9635
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9636 Clearly, if the value returned by evaluating the first argument to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9637 @code{while} is always true, the body following will be evaluated
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9638 again and again @dots{} and again @dots{} forever. Conversely, if the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9639 value returned is never true, the expressions in the body will never
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9640 be evaluated. The craft of writing a @code{while} loop consists of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9641 choosing a mechanism such that the true-or-false-test returns true
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9642 just the number of times that you want the subsequent expressions to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9643 be evaluated, and then have the test return false.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9644
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9645 The value returned by evaluating a @code{while} is the value of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9646 true-or-false-test. An interesting consequence of this is that a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9647 @code{while} loop that evaluates without error will return @code{nil}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9648 or false regardless of whether it has looped 1 or 100 times or none at
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9649 all. A @code{while} expression that evaluates successfully never
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9650 returns a true value! What this means is that @code{while} is always
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9651 evaluated for its side effects, which is to say, the consequences of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9652 evaluating the expressions within the body of the @code{while} loop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9653 This makes sense. It is not the mere act of looping that is desired,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9654 but the consequences of what happens when the expressions in the loop
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9655 are repeatedly evaluated.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9656
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9657 @node Loop Example, print-elements-of-list, Looping with while, while
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9658 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9659 @subsection A @code{while} Loop and a List
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9660
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9661 A common way to control a @code{while} loop is to test whether a list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9662 has any elements. If it does, the loop is repeated; but if it does not,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9663 the repetition is ended. Since this is an important technique, we will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9664 create a short example to illustrate it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9665
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9666 A simple way to test whether a list has elements is to evaluate the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9667 list: if it has no elements, it is an empty list and will return the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9668 empty list, @code{()}, which is a synonym for @code{nil} or false. On
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9669 the other hand, a list with elements will return those elements when it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9670 is evaluated. Since Emacs Lisp considers as true any value that is not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9671 @code{nil}, a list that returns elements will test true in a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9672 @code{while} loop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9673
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9674 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9675 For example, you can set the variable @code{empty-list} to @code{nil} by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9676 evaluating the following @code{setq} expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9677
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9678 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9679 (setq empty-list ())
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9680 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9681
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9682 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9683 After evaluating the @code{setq} expression, you can evaluate the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9684 variable @code{empty-list} in the usual way, by placing the cursor after
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9685 the symbol and typing @kbd{C-x C-e}; @code{nil} will appear in your
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9686 echo area:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9687
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9688 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9689 empty-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9690 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9691
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9692 On the other hand, if you set a variable to be a list with elements, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9693 list will appear when you evaluate the variable, as you can see by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9694 evaluating the following two expressions:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9695
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9696 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9697 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9698 (setq animals '(gazelle giraffe lion tiger))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9699
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9700 animals
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9701 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9702 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9703
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9704 Thus, to create a @code{while} loop that tests whether there are any
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9705 items in the list @code{animals}, the first part of the loop will be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9706 written like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9707
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9708 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9709 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9710 (while animals
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9711 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9712 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9713 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9714
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9715 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9716 When the @code{while} tests its first argument, the variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9717 @code{animals} is evaluated. It returns a list. So long as the list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9718 has elements, the @code{while} considers the results of the test to be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9719 true; but when the list is empty, it considers the results of the test
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9720 to be false.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9721
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9722 To prevent the @code{while} loop from running forever, some mechanism
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9723 needs to be provided to empty the list eventually. An oft-used
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9724 technique is to have one of the subsequent forms in the @code{while}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9725 expression set the value of the list to be the @sc{cdr} of the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9726 Each time the @code{cdr} function is evaluated, the list will be made
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9727 shorter, until eventually only the empty list will be left. At this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9728 point, the test of the @code{while} loop will return false, and the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9729 arguments to the @code{while} will no longer be evaluated.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9730
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9731 For example, the list of animals bound to the variable @code{animals}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9732 can be set to be the @sc{cdr} of the original list with the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9733 following expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9734
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9735 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9736 (setq animals (cdr animals))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9737 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9738
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9739 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9740 If you have evaluated the previous expressions and then evaluate this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9741 expression, you will see @code{(giraffe lion tiger)} appear in the echo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9742 area. If you evaluate the expression again, @code{(lion tiger)} will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9743 appear in the echo area. If you evaluate it again and yet again,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9744 @code{(tiger)} appears and then the empty list, shown by @code{nil}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9745
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9746 A template for a @code{while} loop that uses the @code{cdr} function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9747 repeatedly to cause the true-or-false-test eventually to test false
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9748 looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9749
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9750 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9751 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9752 (while @var{test-whether-list-is-empty}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9753 @var{body}@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9754 @var{set-list-to-cdr-of-list})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9755 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9756 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9757
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9758 This test and use of @code{cdr} can be put together in a function that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9759 goes through a list and prints each element of the list on a line of its
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9760 own.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9761
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9762 @node print-elements-of-list, Incrementing Loop, Loop Example, while
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9763 @subsection An Example: @code{print-elements-of-list}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9764 @findex print-elements-of-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9765
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9766 The @code{print-elements-of-list} function illustrates a @code{while}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9767 loop with a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9768
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9769 @cindex @file{*scratch*} buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9770 The function requires several lines for its output. If you are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9771 reading this in Emacs 21 or a later version, you can evaluate the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9772 following expression inside of Info, as usual.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9773
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9774 If you are using an earlier version of Emacs, you need to copy the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9775 necessary expressions to your @file{*scratch*} buffer and evaluate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9776 them there. This is because the echo area had only one line in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9777 earlier versions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9778
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9779 You can copy the expressions by marking the beginning of the region
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9780 with @kbd{C-@key{SPC}} (@code{set-mark-command}), moving the cursor to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9781 the end of the region and then copying the region using @kbd{M-w}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9782 (@code{copy-region-as-kill}). In the @file{*scratch*} buffer, you can
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9783 yank the expressions back by typing @kbd{C-y} (@code{yank}).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9784
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9785 After you have copied the expressions to the @file{*scratch*} buffer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9786 evaluate each expression in turn. Be sure to evaluate the last
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9787 expression, @code{(print-elements-of-list animals)}, by typing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9788 @kbd{C-u C-x C-e}, that is, by giving an argument to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9789 @code{eval-last-sexp}. This will cause the result of the evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9790 to be printed in the @file{*scratch*} buffer instead of being printed
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9791 in the echo area. (Otherwise you will see something like this in your
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9792 echo area: @code{^Jgiraffe^J^Jgazelle^J^Jlion^J^Jtiger^Jnil}, in which
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9793 each @samp{^J} stands for a `newline'.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9794
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9795 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9796 If you are using Emacs 21 or later, you can evaluate these expressions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9797 directly in the Info buffer, and the echo area will grow to show the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9798 results.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9799
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9800 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9801 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9802 (setq animals '(gazelle giraffe lion tiger))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9803
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9804 (defun print-elements-of-list (list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9805 "Print each element of LIST on a line of its own."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9806 (while list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9807 (print (car list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9808 (setq list (cdr list))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9809
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9810 (print-elements-of-list animals)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9811 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9812 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9813
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9814 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9815 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9816 When you evaluate the three expressions in sequence, you will see
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9817 this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9818
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9819 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9820 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9821 giraffe
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9822
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9823 gazelle
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9824
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9825 lion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9826
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9827 tiger
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9828 nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9829 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9830 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9831
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9832 Each element of the list is printed on a line of its own (that is what
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9833 the function @code{print} does) and then the value returned by the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9834 function is printed. Since the last expression in the function is the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9835 @code{while} loop, and since @code{while} loops always return
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9836 @code{nil}, a @code{nil} is printed after the last element of the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9837
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9838 @node Incrementing Loop, Decrementing Loop, print-elements-of-list, while
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9839 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9840 @subsection A Loop with an Incrementing Counter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9841
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9842 A loop is not useful unless it stops when it ought. Besides
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9843 controlling a loop with a list, a common way of stopping a loop is to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9844 write the first argument as a test that returns false when the correct
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9845 number of repetitions are complete. This means that the loop must
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9846 have a counter---an expression that counts how many times the loop
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9847 repeats itself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9848
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9849 The test can be an expression such as @code{(< count desired-number)}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9850 which returns @code{t} for true if the value of @code{count} is less
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9851 than the @code{desired-number} of repetitions and @code{nil} for false if
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9852 the value of @code{count} is equal to or is greater than the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9853 @code{desired-number}. The expression that increments the count can be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9854 a simple @code{setq} such as @code{(setq count (1+ count))}, where
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9855 @code{1+} is a built-in function in Emacs Lisp that adds 1 to its
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9856 argument. (The expression @code{(1+ count)} has the same result as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9857 @code{(+ count 1)}, but is easier for a human to read.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9858
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9859 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9860 The template for a @code{while} loop controlled by an incrementing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9861 counter looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9862
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9863 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9864 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9865 @var{set-count-to-initial-value}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9866 (while (< count desired-number) ; @r{true-or-false-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9867 @var{body}@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9868 (setq count (1+ count))) ; @r{incrementer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9869 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9870 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9871
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9872 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9873 Note that you need to set the initial value of @code{count}; usually it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9874 is set to 1.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9875
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9876 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9877 * Incrementing Example:: Counting pebbles in a triangle.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9878 * Inc Example parts:: The parts of the function definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9879 * Inc Example altogether:: Putting the function definition together.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9880 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9881
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9882 @node Incrementing Example, Inc Example parts, Incrementing Loop, Incrementing Loop
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9883 @unnumberedsubsubsec Example with incrementing counter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9884
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9885 Suppose you are playing on the beach and decide to make a triangle of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9886 pebbles, putting one pebble in the first row, two in the second row,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9887 three in the third row and so on, like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9888
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9889 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9890 @c pebble diagram
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9891 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9892 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9893 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9894 *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9895 * *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9896 * * *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9897 * * * *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9898 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9899 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9900 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9901 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9902 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9903 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9904 @bullet{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9905 @bullet{} @bullet{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9906 @bullet{} @bullet{} @bullet{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9907 @bullet{} @bullet{} @bullet{} @bullet{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9908 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9909 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9910 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9911 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9912
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9913 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9914 (About 2500 years ago, Pythagoras and others developed the beginnings of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9915 number theory by considering questions such as this.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9916
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9917 Suppose you want to know how many pebbles you will need to make a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9918 triangle with 7 rows?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9919
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9920 Clearly, what you need to do is add up the numbers from 1 to 7. There
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9921 are two ways to do this; start with the smallest number, one, and add up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9922 the list in sequence, 1, 2, 3, 4 and so on; or start with the largest
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9923 number and add the list going down: 7, 6, 5, 4 and so on. Because both
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9924 mechanisms illustrate common ways of writing @code{while} loops, we will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9925 create two examples, one counting up and the other counting down. In
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9926 this first example, we will start with 1 and add 2, 3, 4 and so on.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9927
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9928 If you are just adding up a short list of numbers, the easiest way to do
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9929 it is to add up all the numbers at once. However, if you do not know
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9930 ahead of time how many numbers your list will have, or if you want to be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9931 prepared for a very long list, then you need to design your addition so
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9932 that what you do is repeat a simple process many times instead of doing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9933 a more complex process once.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9934
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9935 For example, instead of adding up all the pebbles all at once, what you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9936 can do is add the number of pebbles in the first row, 1, to the number
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9937 in the second row, 2, and then add the total of those two rows to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9938 third row, 3. Then you can add the number in the fourth row, 4, to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9939 total of the first three rows; and so on.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9940
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9941 The critical characteristic of the process is that each repetitive
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9942 action is simple. In this case, at each step we add only two numbers,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9943 the number of pebbles in the row and the total already found. This
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9944 process of adding two numbers is repeated again and again until the last
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9945 row has been added to the total of all the preceding rows. In a more
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9946 complex loop the repetitive action might not be so simple, but it will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9947 be simpler than doing everything all at once.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9948
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9949 @node Inc Example parts, Inc Example altogether, Incrementing Example, Incrementing Loop
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9950 @unnumberedsubsubsec The parts of the function definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9951
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9952 The preceding analysis gives us the bones of our function definition:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9953 first, we will need a variable that we can call @code{total} that will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9954 be the total number of pebbles. This will be the value returned by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9955 the function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9956
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9957 Second, we know that the function will require an argument: this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9958 argument will be the total number of rows in the triangle. It can be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9959 called @code{number-of-rows}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9960
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9961 Finally, we need a variable to use as a counter. We could call this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9962 variable @code{counter}, but a better name is @code{row-number}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9963 That is because what the counter does is count rows, and a program
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9964 should be written to be as understandable as possible.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9965
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9966 When the Lisp interpreter first starts evaluating the expressions in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9967 function, the value of @code{total} should be set to zero, since we have
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9968 not added anything to it. Then the function should add the number of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9969 pebbles in the first row to the total, and then add the number of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9970 pebbles in the second to the total, and then add the number of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9971 pebbles in the third row to the total, and so on, until there are no
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9972 more rows left to add.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9973
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9974 Both @code{total} and @code{row-number} are used only inside the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9975 function, so they can be declared as local variables with @code{let}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9976 and given initial values. Clearly, the initial value for @code{total}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9977 should be 0. The initial value of @code{row-number} should be 1,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9978 since we start with the first row. This means that the @code{let}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9979 statement will look like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9980
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9981 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9982 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9983 (let ((total 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9984 (row-number 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9985 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9986 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9987 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9988
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9989 After the internal variables are declared and bound to their initial
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9990 values, we can begin the @code{while} loop. The expression that serves
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9991 as the test should return a value of @code{t} for true so long as the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9992 @code{row-number} is less than or equal to the @code{number-of-rows}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9993 (If the expression tests true only so long as the row number is less
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9994 than the number of rows in the triangle, the last row will never be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9995 added to the total; hence the row number has to be either less than or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9996 equal to the number of rows.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9997
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9998 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9999 @findex <= @r{(less than or equal)}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10000 Lisp provides the @code{<=} function that returns true if the value of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10001 its first argument is less than or equal to the value of its second
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10002 argument and false otherwise. So the expression that the @code{while}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10003 will evaluate as its test should look like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10004
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10005 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10006 (<= row-number number-of-rows)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10007 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10008
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10009 The total number of pebbles can be found by repeatedly adding the number
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10010 of pebbles in a row to the total already found. Since the number of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10011 pebbles in the row is equal to the row number, the total can be found by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10012 adding the row number to the total. (Clearly, in a more complex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10013 situation, the number of pebbles in the row might be related to the row
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10014 number in a more complicated way; if this were the case, the row number
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10015 would be replaced by the appropriate expression.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10016
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10017 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10018 (setq total (+ total row-number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10019 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10020
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10021 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10022 What this does is set the new value of @code{total} to be equal to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10023 sum of adding the number of pebbles in the row to the previous total.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10024
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10025 After setting the value of @code{total}, the conditions need to be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10026 established for the next repetition of the loop, if there is one. This
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10027 is done by incrementing the value of the @code{row-number} variable,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10028 which serves as a counter. After the @code{row-number} variable has
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10029 been incremented, the true-or-false-test at the beginning of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10030 @code{while} loop tests whether its value is still less than or equal to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10031 the value of the @code{number-of-rows} and if it is, adds the new value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10032 of the @code{row-number} variable to the @code{total} of the previous
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10033 repetition of the loop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10034
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10035 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10036 The built-in Emacs Lisp function @code{1+} adds 1 to a number, so the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10037 @code{row-number} variable can be incremented with this expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10038
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10039 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10040 (setq row-number (1+ row-number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10041 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10042
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10043 @node Inc Example altogether, , Inc Example parts, Incrementing Loop
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10044 @unnumberedsubsubsec Putting the function definition together
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10045
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10046 We have created the parts for the function definition; now we need to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10047 put them together.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10048
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10049 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10050 First, the contents of the @code{while} expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10051
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10052 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10053 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10054 (while (<= row-number number-of-rows) ; @r{true-or-false-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10055 (setq total (+ total row-number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10056 (setq row-number (1+ row-number))) ; @r{incrementer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10057 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10058 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10059
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10060 Along with the @code{let} expression varlist, this very nearly
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10061 completes the body of the function definition. However, it requires
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10062 one final element, the need for which is somewhat subtle.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10063
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10064 The final touch is to place the variable @code{total} on a line by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10065 itself after the @code{while} expression. Otherwise, the value returned
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10066 by the whole function is the value of the last expression that is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10067 evaluated in the body of the @code{let}, and this is the value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10068 returned by the @code{while}, which is always @code{nil}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10069
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10070 This may not be evident at first sight. It almost looks as if the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10071 incrementing expression is the last expression of the whole function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10072 But that expression is part of the body of the @code{while}; it is the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10073 last element of the list that starts with the symbol @code{while}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10074 Moreover, the whole of the @code{while} loop is a list within the body
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10075 of the @code{let}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10076
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10077 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10078 In outline, the function will look like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10079
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10080 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10081 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10082 (defun @var{name-of-function} (@var{argument-list})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10083 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10084 (let (@var{varlist})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10085 (while (@var{true-or-false-test})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10086 @var{body-of-while}@dots{} )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10087 @dots{} ) ; @r{Need final expression here.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10088 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10089 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10090
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10091 The result of evaluating the @code{let} is what is going to be returned
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10092 by the @code{defun} since the @code{let} is not embedded within any
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10093 containing list, except for the @code{defun} as a whole. However, if
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10094 the @code{while} is the last element of the @code{let} expression, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10095 function will always return @code{nil}. This is not what we want!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10096 Instead, what we want is the value of the variable @code{total}. This
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10097 is returned by simply placing the symbol as the last element of the list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10098 starting with @code{let}. It gets evaluated after the preceding
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10099 elements of the list are evaluated, which means it gets evaluated after
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10100 it has been assigned the correct value for the total.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10101
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10102 It may be easier to see this by printing the list starting with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10103 @code{let} all on one line. This format makes it evident that the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10104 @var{varlist} and @code{while} expressions are the second and third
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10105 elements of the list starting with @code{let}, and the @code{total} is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10106 the last element:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10107
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10108 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10109 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10110 (let (@var{varlist}) (while (@var{true-or-false-test}) @var{body-of-while}@dots{} ) total)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10111 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10112 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10113
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10114 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10115 Putting everything together, the @code{triangle} function definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10116 looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10117
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10118 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10119 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10120 (defun triangle (number-of-rows) ; @r{Version with}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10121 ; @r{ incrementing counter.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10122 "Add up the number of pebbles in a triangle.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10123 The first row has one pebble, the second row two pebbles,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10124 the third row three pebbles, and so on.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10125 The argument is NUMBER-OF-ROWS."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10126 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10127 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10128 (let ((total 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10129 (row-number 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10130 (while (<= row-number number-of-rows)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10131 (setq total (+ total row-number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10132 (setq row-number (1+ row-number)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10133 total))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10134 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10135 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10136
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10137 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10138 After you have installed @code{triangle} by evaluating the function, you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10139 can try it out. Here are two examples:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10140
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10141 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10142 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10143 (triangle 4)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10144
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10145 (triangle 7)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10146 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10147 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10148
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10149 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10150 The sum of the first four numbers is 10 and the sum of the first seven
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10151 numbers is 28.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10152
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10153 @node Decrementing Loop, , Incrementing Loop, while
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10154 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10155 @subsection Loop with a Decrementing Counter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10156
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10157 Another common way to write a @code{while} loop is to write the test
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10158 so that it determines whether a counter is greater than zero. So long
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10159 as the counter is greater than zero, the loop is repeated. But when
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10160 the counter is equal to or less than zero, the loop is stopped. For
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10161 this to work, the counter has to start out greater than zero and then
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10162 be made smaller and smaller by a form that is evaluated
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10163 repeatedly.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10164
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10165 The test will be an expression such as @code{(> counter 0)} which
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10166 returns @code{t} for true if the value of @code{counter} is greater
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10167 than zero, and @code{nil} for false if the value of @code{counter} is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10168 equal to or less than zero. The expression that makes the number
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10169 smaller and smaller can be a simple @code{setq} such as @code{(setq
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10170 counter (1- counter))}, where @code{1-} is a built-in function in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10171 Emacs Lisp that subtracts 1 from its argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10172
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10173 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10174 The template for a decrementing @code{while} loop looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10175
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10176 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10177 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10178 (while (> counter 0) ; @r{true-or-false-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10179 @var{body}@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10180 (setq counter (1- counter))) ; @r{decrementer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10181 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10182 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10183
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10184 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10185 * Decrementing Example:: More pebbles on the beach.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10186 * Dec Example parts:: The parts of the function definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10187 * Dec Example altogether:: Putting the function definition together.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10188 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10189
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10190 @node Decrementing Example, Dec Example parts, Decrementing Loop, Decrementing Loop
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10191 @unnumberedsubsubsec Example with decrementing counter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10192
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10193 To illustrate a loop with a decrementing counter, we will rewrite the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10194 @code{triangle} function so the counter decreases to zero.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10195
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10196 This is the reverse of the earlier version of the function. In this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10197 case, to find out how many pebbles are needed to make a triangle with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10198 3 rows, add the number of pebbles in the third row, 3, to the number
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10199 in the preceding row, 2, and then add the total of those two rows to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10200 the row that precedes them, which is 1.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10201
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10202 Likewise, to find the number of pebbles in a triangle with 7 rows, add
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10203 the number of pebbles in the seventh row, 7, to the number in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10204 preceding row, which is 6, and then add the total of those two rows to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10205 the row that precedes them, which is 5, and so on. As in the previous
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10206 example, each addition only involves adding two numbers, the total of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10207 the rows already added up and the number of pebbles in the row that is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10208 being added to the total. This process of adding two numbers is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10209 repeated again and again until there are no more pebbles to add.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10210
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10211 We know how many pebbles to start with: the number of pebbles in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10212 last row is equal to the number of rows. If the triangle has seven
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10213 rows, the number of pebbles in the last row is 7. Likewise, we know how
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10214 many pebbles are in the preceding row: it is one less than the number in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10215 the row.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10216
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10217 @node Dec Example parts, Dec Example altogether, Decrementing Example, Decrementing Loop
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10218 @unnumberedsubsubsec The parts of the function definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10219
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10220 We start with three variables: the total number of rows in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10221 triangle; the number of pebbles in a row; and the total number of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10222 pebbles, which is what we want to calculate. These variables can be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10223 named @code{number-of-rows}, @code{number-of-pebbles-in-row}, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10224 @code{total}, respectively.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10225
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10226 Both @code{total} and @code{number-of-pebbles-in-row} are used only
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10227 inside the function and are declared with @code{let}. The initial
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10228 value of @code{total} should, of course, be zero. However, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10229 initial value of @code{number-of-pebbles-in-row} should be equal to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10230 the number of rows in the triangle, since the addition will start with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10231 the longest row.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10232
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10233 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10234 This means that the beginning of the @code{let} expression will look
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10235 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10236
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10237 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10238 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10239 (let ((total 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10240 (number-of-pebbles-in-row number-of-rows))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10241 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10242 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10243 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10244
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10245 The total number of pebbles can be found by repeatedly adding the number
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10246 of pebbles in a row to the total already found, that is, by repeatedly
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10247 evaluating the following expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10248
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10249 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10250 (setq total (+ total number-of-pebbles-in-row))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10251 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10252
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10253 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10254 After the @code{number-of-pebbles-in-row} is added to the @code{total},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10255 the @code{number-of-pebbles-in-row} should be decremented by one, since
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10256 the next time the loop repeats, the preceding row will be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10257 added to the total.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10258
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10259 The number of pebbles in a preceding row is one less than the number of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10260 pebbles in a row, so the built-in Emacs Lisp function @code{1-} can be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10261 used to compute the number of pebbles in the preceding row. This can be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10262 done with the following expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10263
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10264 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10265 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10266 (setq number-of-pebbles-in-row
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10267 (1- number-of-pebbles-in-row))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10268 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10269 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10270
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10271 Finally, we know that the @code{while} loop should stop making repeated
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10272 additions when there are no pebbles in a row. So the test for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10273 the @code{while} loop is simply:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10274
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10275 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10276 (while (> number-of-pebbles-in-row 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10277 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10278
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10279 @node Dec Example altogether, , Dec Example parts, Decrementing Loop
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10280 @unnumberedsubsubsec Putting the function definition together
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10281
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10282 We can put these expressions together to create a function definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10283 that works. However, on examination, we find that one of the local
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10284 variables is unneeded!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10285
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10286 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10287 The function definition looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10288
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10289 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10290 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10291 ;;; @r{First subtractive version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10292 (defun triangle (number-of-rows)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10293 "Add up the number of pebbles in a triangle."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10294 (let ((total 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10295 (number-of-pebbles-in-row number-of-rows))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10296 (while (> number-of-pebbles-in-row 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10297 (setq total (+ total number-of-pebbles-in-row))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10298 (setq number-of-pebbles-in-row
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10299 (1- number-of-pebbles-in-row)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10300 total))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10301 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10302 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10303
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10304 As written, this function works.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10305
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10306 However, we do not need @code{number-of-pebbles-in-row}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10307
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10308 @cindex Argument as local variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10309 When the @code{triangle} function is evaluated, the symbol
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10310 @code{number-of-rows} will be bound to a number, giving it an initial
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10311 value. That number can be changed in the body of the function as if
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10312 it were a local variable, without any fear that such a change will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10313 effect the value of the variable outside of the function. This is a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10314 very useful characteristic of Lisp; it means that the variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10315 @code{number-of-rows} can be used anywhere in the function where
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10316 @code{number-of-pebbles-in-row} is used.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10317
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10318 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10319 Here is a second version of the function written a bit more cleanly:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10320
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10321 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10322 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10323 (defun triangle (number) ; @r{Second version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10324 "Return sum of numbers 1 through NUMBER inclusive."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10325 (let ((total 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10326 (while (> number 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10327 (setq total (+ total number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10328 (setq number (1- number)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10329 total))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10330 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10331 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10332
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10333 In brief, a properly written @code{while} loop will consist of three parts:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10334
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10335 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10336 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10337 A test that will return false after the loop has repeated itself the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10338 correct number of times.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10339
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10340 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10341 An expression the evaluation of which will return the value desired
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10342 after being repeatedly evaluated.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10343
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10344 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10345 An expression to change the value passed to the true-or-false-test so
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10346 that the test returns false after the loop has repeated itself the right
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10347 number of times.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10348 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10349
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10350 @node dolist dotimes, Recursion, while, Loops & Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10351 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10352 @section Save your time: @code{dolist} and @code{dotimes}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10353
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10354 In addition to @code{while}, both @code{dolist} and @code{dotimes}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10355 provide for looping. Sometimes these are quicker to write than the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10356 equivalent @code{while} loop. Both are Lisp macros. (@xref{Macros, ,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10357 Macros, elisp, The GNU Emacs Lisp Reference Manual}. )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10358
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10359 @code{dolist} works like a @code{while} loop that `@sc{cdr}s down a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10360 list': @code{dolist} automatically shortens the list each time it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10361 loops---takes the @sc{cdr} of the list---and binds the @sc{car} of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10362 each shorter version of the list to the first of its arguments.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10363
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10364 @code{dotimes} loops a specific number of time: you specify the number.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10365
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10366 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10367 * dolist::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10368 * dotimes::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10369 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10370
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10371 @node dolist, dotimes, dolist dotimes, dolist dotimes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10372 @unnumberedsubsubsec The @code{dolist} Macro
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10373 @findex dolist
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10374
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10375 Suppose, for example, you want to reverse a list, so that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10376 ``first'' ``second'' ``third'' becomes ``third'' ``second'' ``first''.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10377
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10378 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10379 In practice, you would use the @code{reverse} function, like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10380
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10381 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10382 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10383 (setq animals '(gazelle giraffe lion tiger))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10384
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10385 (reverse animals)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10386 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10387 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10388
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10389 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10390 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10391 Here is how you could reverse the list using a @code{while} loop:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10392
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10393 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10394 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10395 (setq animals '(gazelle giraffe lion tiger))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10396
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10397 (defun reverse-list-with-while (list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10398 "Using while, reverse the order of LIST."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10399 (let (value) ; make sure list starts empty
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10400 (while list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10401 (setq value (cons (car list) value))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10402 (setq list (cdr list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10403 value))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10404
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10405 (reverse-list-with-while animals)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10406 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10407 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10408
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10409 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10410 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10411 And here is how you could use the @code{dolist} macro:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10412
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10413 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10414 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10415 (setq animals '(gazelle giraffe lion tiger))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10416
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10417 (defun reverse-list-with-dolist (list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10418 "Using dolist, reverse the order of LIST."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10419 (let (value) ; make sure list starts empty
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10420 (dolist (element list value)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10421 (setq value (cons element value)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10422
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10423 (reverse-list-with-dolist animals)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10424 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10425 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10426
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10427 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10428 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10429 In Info, you can place your cursor after the closing parenthesis of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10430 each expression and type @kbd{C-x C-e}; in each case, you should see
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10431
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10432 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10433 (tiger lion giraffe gazelle)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10434 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10435
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10436 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10437 in the echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10438
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10439 For this example, the existing @code{reverse} function is obviously best.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10440 The @code{while} loop is just like our first example (@pxref{Loop
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10441 Example, , A @code{while} Loop and a List}). The @code{while} first
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10442 checks whether the list has elements; if so, it constructs a new list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10443 by adding the first element of the list to the existing list (which in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10444 the first iteration of the loop is @code{nil}). Since the second
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10445 element is prepended in front of the first element, and the third
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10446 element is prepended in front of the second element, the list is reversed.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10447
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10448 In the expression using a @code{while} loop,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10449 the @w{@code{(setq list (cdr list))}}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10450 expression shortens the list, so the @code{while} loop eventually
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10451 stops. In addition, it provides the @code{cons} expression with a new
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10452 first element by creating a new and shorter list at each repetition of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10453 the loop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10454
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10455 The @code{dolist} expression does very much the same as the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10456 @code{while} expression, except that the @code{dolist} macro does some
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10457 of the work you have to do when writing a @code{while} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10458
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10459 Like a @code{while} loop, a @code{dolist} loops. What is different is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10460 that it automatically shortens the list each time it loops --- it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10461 `@sc{cdr}s down the list' on its own --- and it automatically binds
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10462 the @sc{car} of each shorter version of the list to the first of its
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10463 arguments.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10464
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10465 In the example, the @sc{car} of each shorter version of the list is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10466 referred to using the symbol @samp{element}, the list itself is called
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10467 @samp{list}, and the value returned is called @samp{value}. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10468 remainder of the @code{dolist} expression is the body.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10469
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10470 The @code{dolist} expression binds the @sc{car} of each shorter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10471 version of the list to @code{element} and then evaluates the body of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10472 the expression; and repeats the loop. The result is returned in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10473 @code{value}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10474
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10475 @node dotimes, , dolist, dolist dotimes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10476 @unnumberedsubsubsec The @code{dotimes} Macro
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10477 @findex dotimes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10478
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10479 The @code{dotimes} macro is similar to @code{dolist}, except that it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10480 loops a specific number of times.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10481
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10482 The first argument to @code{dotimes} is assigned the numbers 0, 1, 2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10483 and so forth each time around the loop, and the value of the third
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10484 argument is returned. You need to provide the value of the second
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10485 argument, which is how many times the macro loops.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10486
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10487 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10488 For example, the following binds the numbers from 0 up to, but not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10489 including, the number 3 to the first argument, @var{number}, and then
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10490 constructs a list of the three numbers. (The first number is 0, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10491 second number is 1, and the third number is 2; this makes a total of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10492 three numbers in all, starting with zero as the first number.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10493
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10494 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10495 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10496 (let (value) ; otherwise a value is a void variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10497 (dotimes (number 3 value)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10498 (setq value (cons number value))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10499
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10500 @result{} (2 1 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10501 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10502 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10503
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10504 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10505 @code{dotimes} returns @code{value}, so the way to use
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10506 @code{dotimes} is to operate on some expression @var{number} number of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10507 times and then return the result, either as a list or an atom.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10508
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10509 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10510 Here is an example of a @code{defun} that uses @code{dotimes} to add
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10511 up the number of pebbles in a triangle.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10512
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10513 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10514 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10515 (defun triangle-using-dotimes (number-of-rows)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10516 "Using dotimes, add up the number of pebbles in a triangle."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10517 (let ((total 0)) ; otherwise a total is a void variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10518 (dotimes (number number-of-rows total)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10519 (setq total (+ total (1+ number))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10520
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10521 (triangle-using-dotimes 4)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10522 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10523 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10524
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10525 @node Recursion, Looping exercise, dolist dotimes, Loops & Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10526 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10527 @section Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10528 @cindex Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10529
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10530 A recursive function contains code that tells the Lisp interpreter to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10531 call a program that runs exactly like itself, but with slightly
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10532 different arguments. The code runs exactly the same because it has
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10533 the same name. However, even though it has the same name, it is not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10534 the same thread of execution. It is different. In the jargon, it is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10535 a different `instance'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10536
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10537 Eventually, if the program is written correctly, the `slightly
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10538 different arguments' will become sufficiently different from the first
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10539 arguments that the final instance will stop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10540
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10541 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10542 * Building Robots:: Same model, different serial number ...
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10543 * Recursive Definition Parts:: Walk until you stop ...
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10544 * Recursion with list:: Using a list as the test whether to recurse.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10545 * Recursive triangle function::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10546 * Recursion with cond::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10547 * Recursive Patterns:: Often used templates.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10548 * No Deferment:: Don't store up work ...
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10549 * No deferment solution::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10550 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10551
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10552 @node Building Robots, Recursive Definition Parts, Recursion, Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10553 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10554 @subsection Building Robots: Extending the Metaphor
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10555 @cindex Building robots
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10556 @cindex Robots, building
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10557
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10558 It is sometimes helpful to think of a running program as a robot that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10559 does a job. In doing its job, a recursive function calls on a second
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10560 robot to help it. The second robot is identical to the first in every
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10561 way, except that the second robot helps the first and has been
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10562 passed different arguments than the first.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10563
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10564 In a recursive function, the second robot may call a third; and the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10565 third may call a fourth, and so on. Each of these is a different
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10566 entity; but all are clones.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10567
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10568 Since each robot has slightly different instructions---the arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10569 will differ from one robot to the next---the last robot should know
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10570 when to stop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10571
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10572 Let's expand on the metaphor in which a computer program is a robot.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10573
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10574 A function definition provides the blueprints for a robot. When you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10575 install a function definition, that is, when you evaluate a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10576 @code{defun} special form, you install the necessary equipment to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10577 build robots. It is as if you were in a factory, setting up an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10578 assembly line. Robots with the same name are built according to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10579 same blueprints. So they have, as it were, the same `model number',
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10580 but a different `serial number'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10581
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10582 We often say that a recursive function `calls itself'. What we mean
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10583 is that the instructions in a recursive function cause the Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10584 interpreter to run a different function that has the same name and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10585 does the same job as the first, but with different arguments.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10586
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10587 It is important that the arguments differ from one instance to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10588 next; otherwise, the process will never stop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10589
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10590 @node Recursive Definition Parts, Recursion with list, Building Robots, Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10591 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10592 @subsection The Parts of a Recursive Definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10593 @cindex Parts of a Recursive Definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10594 @cindex Recursive Definition Parts
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10595
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10596 A recursive function typically contains a conditional expression which
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10597 has three parts:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10598
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10599 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10600 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10601 A true-or-false-test that determines whether the function is called
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10602 again, here called the @dfn{do-again-test}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10603
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10604 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10605 The name of the function. When this name is called, a new instance of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10606 the function---a new robot, as it were---is created and told what to do.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10607
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10608 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10609 An expression that returns a different value each time the function is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10610 called, here called the @dfn{next-step-expression}. Consequently, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10611 argument (or arguments) passed to the new instance of the function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10612 will be different from that passed to the previous instance. This
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10613 causes the conditional expression, the @dfn{do-again-test}, to test
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10614 false after the correct number of repetitions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10615 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10616
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10617 Recursive functions can be much simpler than any other kind of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10618 function. Indeed, when people first start to use them, they often look
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10619 so mysteriously simple as to be incomprehensible. Like riding a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10620 bicycle, reading a recursive function definition takes a certain knack
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10621 which is hard at first but then seems simple.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10622
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10623 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10624 There are several different common recursive patterns. A very simple
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10625 pattern looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10626
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10627 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10628 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10629 (defun @var{name-of-recursive-function} (@var{argument-list})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10630 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10631 (if @var{do-again-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10632 @var{body}@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10633 (@var{name-of-recursive-function}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10634 @var{next-step-expression})))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10635 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10636 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10637
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10638 Each time a recursive function is evaluated, a new instance of it is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10639 created and told what to do. The arguments tell the instance what to do.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10640
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10641 An argument is bound to the value of the next-step-expression. Each
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10642 instance runs with a different value of the next-step-expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10643
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10644 The value in the next-step-expression is used in the do-again-test.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10645
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10646 The value returned by the next-step-expression is passed to the new
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10647 instance of the function, which evaluates it (or some
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10648 transmogrification of it) to determine whether to continue or stop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10649 The next-step-expression is designed so that the do-again-test returns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10650 false when the function should no longer be repeated.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10651
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10652 The do-again-test is sometimes called the @dfn{stop condition},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10653 since it stops the repetitions when it tests false.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10654
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10655 @node Recursion with list, Recursive triangle function, Recursive Definition Parts, Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10656 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10657 @subsection Recursion with a List
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10658
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10659 The example of a @code{while} loop that printed the elements of a list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10660 of numbers can be written recursively. Here is the code, including
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10661 an expression to set the value of the variable @code{animals} to a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10662
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10663 If you are using Emacs 20 or before, this example must be copied to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10664 the @file{*scratch*} buffer and each expression must be evaluated
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10665 there. Use @kbd{C-u C-x C-e} to evaluate the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10666 @code{(print-elements-recursively animals)} expression so that the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10667 results are printed in the buffer; otherwise the Lisp interpreter will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10668 try to squeeze the results into the one line of the echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10669
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10670 Also, place your cursor immediately after the last closing parenthesis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10671 of the @code{print-elements-recursively} function, before the comment.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10672 Otherwise, the Lisp interpreter will try to evaluate the comment.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10673
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10674 If you are using Emacs 21 or later, you can evaluate this expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10675 directly in Info.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10676
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10677 @findex print-elements-recursively
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10678 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10679 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10680 (setq animals '(gazelle giraffe lion tiger))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10681
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10682 (defun print-elements-recursively (list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10683 "Print each element of LIST on a line of its own.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10684 Uses recursion."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10685 (if list ; @r{do-again-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10686 (progn
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10687 (print (car list)) ; @r{body}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10688 (print-elements-recursively ; @r{recursive call}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10689 (cdr list))))) ; @r{next-step-expression}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10690
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10691 (print-elements-recursively animals)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10692 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10693 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10694
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10695 The @code{print-elements-recursively} function first tests whether
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10696 there is any content in the list; if there is, the function prints the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10697 first element of the list, the @sc{car} of the list. Then the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10698 function `invokes itself', but gives itself as its argument, not the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10699 whole list, but the second and subsequent elements of the list, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10700 @sc{cdr} of the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10701
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10702 Put another way, if the list is not empty, the function invokes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10703 another instance of code that is similar to the initial code, but is a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10704 different thread of execution, with different arguments than the first
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10705 instance.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10706
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10707 Put in yet another way, if the list is not empty, the first robot
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10708 assemblies a second robot and tells it what to do; the second robot is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10709 a different individual from the first, but is the same model.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10710
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10711 When the second evaluation occurs, the @code{if} expression is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10712 evaluated and if true, prints the first element of the list it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10713 receives as its argument (which is the second element of the original
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10714 list). Then the function `calls itself' with the @sc{cdr} of the list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10715 it is invoked with, which (the second time around) is the @sc{cdr} of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10716 the @sc{cdr} of the original list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10717
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10718 Note that although we say that the function `calls itself', what we
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10719 mean is that the Lisp interpreter assembles and instructs a new
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10720 instance of the program. The new instance is a clone of the first,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10721 but is a separate individual.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10722
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10723 Each time the function `invokes itself', it invokes itself on a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10724 shorter version of the original list. It creates a new instance that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10725 works on a shorter list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10726
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10727 Eventually, the function invokes itself on an empty list. It creates
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10728 a new instance whose argument is @code{nil}. The conditional expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10729 tests the value of @code{list}. Since the value of @code{list} is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10730 @code{nil}, the @code{if} expression tests false so the then-part is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10731 not evaluated. The function as a whole then returns @code{nil}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10732
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10733 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10734 When you evaluate @code{(print-elements-recursively animals)} in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10735 @file{*scratch*} buffer, you see this result:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10736
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10737 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10738 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10739 giraffe
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10740
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10741 gazelle
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10742
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10743 lion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10744
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10745 tiger
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10746 nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10747 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10748 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10749
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10750 @node Recursive triangle function, Recursion with cond, Recursion with list, Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10751 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10752 @subsection Recursion in Place of a Counter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10753 @findex triangle-recursively
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10754
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10755 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10756 The @code{triangle} function described in a previous section can also
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10757 be written recursively. It looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10758
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10759 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10760 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10761 (defun triangle-recursively (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10762 "Return the sum of the numbers 1 through NUMBER inclusive.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10763 Uses recursion."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10764 (if (= number 1) ; @r{do-again-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10765 1 ; @r{then-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10766 (+ number ; @r{else-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10767 (triangle-recursively ; @r{recursive call}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10768 (1- number))))) ; @r{next-step-expression}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10769
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10770 (triangle-recursively 7)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10771 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10772 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10773
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10774 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10775 You can install this function by evaluating it and then try it by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10776 evaluating @code{(triangle-recursively 7)}. (Remember to put your
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10777 cursor immediately after the last parenthesis of the function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10778 definition, before the comment.) The function evaluates to 28.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10779
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10780 To understand how this function works, let's consider what happens in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10781 various cases when the function is passed 1, 2, 3, or 4 as the value of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10782 its argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10783
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10784 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10785 * Recursive Example arg of 1 or 2::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10786 * Recursive Example arg of 3 or 4::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10787 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10788
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10789 @node Recursive Example arg of 1 or 2, Recursive Example arg of 3 or 4, Recursive triangle function, Recursive triangle function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10790 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10791 @unnumberedsubsubsec An argument of 1 or 2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10792 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10793
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10794 First, what happens if the value of the argument is 1?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10795
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10796 The function has an @code{if} expression after the documentation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10797 string. It tests whether the value of @code{number} is equal to 1; if
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10798 so, Emacs evaluates the then-part of the @code{if} expression, which
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10799 returns the number 1 as the value of the function. (A triangle with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10800 one row has one pebble in it.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10801
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10802 Suppose, however, that the value of the argument is 2. In this case,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10803 Emacs evaluates the else-part of the @code{if} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10804
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10805 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10806 The else-part consists of an addition, the recursive call to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10807 @code{triangle-recursively} and a decrementing action; and it looks like
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10808 this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10809
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10810 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10811 (+ number (triangle-recursively (1- number)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10812 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10813
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10814 When Emacs evaluates this expression, the innermost expression is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10815 evaluated first; then the other parts in sequence. Here are the steps
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10816 in detail:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10817
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10818 @table @i
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10819 @item Step 1 @w{ } Evaluate the innermost expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10820
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10821 The innermost expression is @code{(1- number)} so Emacs decrements the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10822 value of @code{number} from 2 to 1.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10823
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10824 @item Step 2 @w{ } Evaluate the @code{triangle-recursively} function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10825
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10826 The Lisp interpreter creates an individual instance of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10827 @code{triangle-recursively}. It does not matter that this function is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10828 contained within itself. Emacs passes the result Step 1 as the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10829 argument used by this instance of the @code{triangle-recursively}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10830 function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10831
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10832 In this case, Emacs evaluates @code{triangle-recursively} with an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10833 argument of 1. This means that this evaluation of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10834 @code{triangle-recursively} returns 1.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10835
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10836 @item Step 3 @w{ } Evaluate the value of @code{number}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10837
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10838 The variable @code{number} is the second element of the list that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10839 starts with @code{+}; its value is 2.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10840
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10841 @item Step 4 @w{ } Evaluate the @code{+} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10842
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10843 The @code{+} expression receives two arguments, the first
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10844 from the evaluation of @code{number} (Step 3) and the second from the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10845 evaluation of @code{triangle-recursively} (Step 2).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10846
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10847 The result of the addition is the sum of 2 plus 1, and the number 3 is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10848 returned, which is correct. A triangle with two rows has three
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10849 pebbles in it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10850 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10851
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10852 @node Recursive Example arg of 3 or 4, , Recursive Example arg of 1 or 2, Recursive triangle function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10853 @unnumberedsubsubsec An argument of 3 or 4
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10854
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10855 Suppose that @code{triangle-recursively} is called with an argument of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10856 3.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10857
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10858 @table @i
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10859 @item Step 1 @w{ } Evaluate the do-again-test.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10860
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10861 The @code{if} expression is evaluated first. This is the do-again
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10862 test and returns false, so the else-part of the @code{if} expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10863 is evaluated. (Note that in this example, the do-again-test causes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10864 the function to call itself when it tests false, not when it tests
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10865 true.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10866
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10867 @item Step 2 @w{ } Evaluate the innermost expression of the else-part.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10868
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10869 The innermost expression of the else-part is evaluated, which decrements
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10870 3 to 2. This is the next-step-expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10871
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10872 @item Step 3 @w{ } Evaluate the @code{triangle-recursively} function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10873
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10874 The number 2 is passed to the @code{triangle-recursively} function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10875
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10876 We know what happens when Emacs evaluates @code{triangle-recursively} with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10877 an argument of 2. After going through the sequence of actions described
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10878 earlier, it returns a value of 3. So that is what will happen here.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10879
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10880 @item Step 4 @w{ } Evaluate the addition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10881
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10882 3 will be passed as an argument to the addition and will be added to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10883 number with which the function was called, which is 3.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10884 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10885
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10886 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10887 The value returned by the function as a whole will be 6.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10888
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10889 Now that we know what will happen when @code{triangle-recursively} is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10890 called with an argument of 3, it is evident what will happen if it is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10891 called with an argument of 4:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10892
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10893 @quotation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10894 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10895 In the recursive call, the evaluation of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10896
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10897 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10898 (triangle-recursively (1- 4))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10899 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10900
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10901 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10902 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10903 will return the value of evaluating
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10904
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10905 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10906 (triangle-recursively 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10907 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10908
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10909 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10910 which is 6 and this value will be added to 4 by the addition in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10911 third line.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10912 @end quotation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10913
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10914 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10915 The value returned by the function as a whole will be 10.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10916
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10917 Each time @code{triangle-recursively} is evaluated, it evaluates a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10918 version of itself---a different instance of itself---with a smaller
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10919 argument, until the argument is small enough so that it does not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10920 evaluate itself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10921
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10922 Note that this particular design for a recursive function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10923 requires that operations be deferred.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10924
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10925 Before @code{(triangle-recursively 7)} can calculate its answer, it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10926 must call @code{(triangle-recursively 6)}; and before
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10927 @code{(triangle-recursively 6)} can calculate its answer, it must call
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10928 @code{(triangle-recursively 5)}; and so on. That is to say, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10929 calculation that @code{(triangle-recursively 7)} makes must be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10930 deferred until @code{(triangle-recursively 6)} makes its calculation;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10931 and @code{(triangle-recursively 6)} must defer until
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10932 @code{(triangle-recursively 5)} completes; and so on.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10933
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10934 If each of these instances of @code{triangle-recursively} are thought
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10935 of as different robots, the first robot must wait for the second to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10936 complete its job, which must wait until the third completes, and so
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10937 on.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10938
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10939 There is a way around this kind of waiting, which we will discuss in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10940 @ref{No Deferment, , Recursion without Deferments}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10941
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10942 @node Recursion with cond, Recursive Patterns, Recursive triangle function, Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10943 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10944 @subsection Recursion Example Using @code{cond}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10945 @findex cond
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10946
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10947 The version of @code{triangle-recursively} described earlier is written
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10948 with the @code{if} special form. It can also be written using another
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10949 special form called @code{cond}. The name of the special form
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10950 @code{cond} is an abbreviation of the word @samp{conditional}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10951
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10952 Although the @code{cond} special form is not used as often in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10953 Emacs Lisp sources as @code{if}, it is used often enough to justify
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10954 explaining it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10955
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10956 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10957 The template for a @code{cond} expression looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10958
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10959 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10960 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10961 (cond
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10962 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10963 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10964 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10965
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10966 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10967 where the @var{body} is a series of lists.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10968
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10969 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10970 Written out more fully, the template looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10971
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10972 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10973 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10974 (cond
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10975 (@var{first-true-or-false-test} @var{first-consequent})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10976 (@var{second-true-or-false-test} @var{second-consequent})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10977 (@var{third-true-or-false-test} @var{third-consequent})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10978 @dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10979 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10980 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10981
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10982 When the Lisp interpreter evaluates the @code{cond} expression, it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10983 evaluates the first element (the @sc{car} or true-or-false-test) of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10984 the first expression in a series of expressions within the body of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10985 @code{cond}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10986
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10987 If the true-or-false-test returns @code{nil} the rest of that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10988 expression, the consequent, is skipped and the true-or-false-test of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10989 next expression is evaluated. When an expression is found whose
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10990 true-or-false-test returns a value that is not @code{nil}, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10991 consequent of that expression is evaluated. The consequent can be one
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10992 or more expressions. If the consequent consists of more than one
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10993 expression, the expressions are evaluated in sequence and the value of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10994 the last one is returned. If the expression does not have a consequent,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10995 the value of the true-or-false-test is returned.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10996
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10997 If none of the true-or-false-tests test true, the @code{cond} expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10998 returns @code{nil}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10999
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11000 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11001 Written using @code{cond}, the @code{triangle} function looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11002
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11003 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11004 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11005 (defun triangle-using-cond (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11006 (cond ((<= number 0) 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11007 ((= number 1) 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11008 ((> number 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11009 (+ number (triangle-using-cond (1- number))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11010 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11011 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11012
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11013 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11014 In this example, the @code{cond} returns 0 if the number is less than or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11015 equal to 0, it returns 1 if the number is 1 and it evaluates @code{(+
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11016 number (triangle-using-cond (1- number)))} if the number is greater than
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11017 1.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11018
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11019 @node Recursive Patterns, No Deferment, Recursion with cond, Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11020 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11021 @subsection Recursive Patterns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11022 @cindex Recursive Patterns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11023
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11024 Here are three common recursive patterns. Each involves a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11025 Recursion does not need to involve lists, but Lisp is designed for lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11026 and this provides a sense of its primal capabilities.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11027
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11028 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11029 * Every::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11030 * Accumulate::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11031 * Keep::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11032 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11033
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11034 @node Every, Accumulate, Recursive Patterns, Recursive Patterns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11035 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11036 @unnumberedsubsubsec Recursive Pattern: @emph{every}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11037 @cindex Every, type of recursive pattern
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11038 @cindex Recursive pattern: every
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11039
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11040 In the @code{every} recursive pattern, an action is performed on every
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11041 element of a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11042
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11043 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11044 The basic pattern is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11045
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11046 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11047 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11048 If a list be empty, return @code{nil}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11049 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11050 Else, act on the beginning of the list (the @sc{car} of the list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11051 @itemize @minus
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11052 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11053 through a recursive call by the function on the rest (the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11054 @sc{cdr}) of the list,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11055 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11056 and, optionally, combine the acted-on element, using @code{cons},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11057 with the results of acting on the rest.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11058 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11059 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11060
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11061 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11062 Here is example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11063
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11064 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11065 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11066 (defun square-each (numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11067 "Square each of a NUMBERS LIST, recursively."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11068 (if (not numbers-list) ; do-again-test
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11069 nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11070 (cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11071 (* (car numbers-list) (car numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11072 (square-each (cdr numbers-list))))) ; next-step-expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11073 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11074
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11075 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11076 (square-each '(1 2 3))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11077 @result{} (1 4 9)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11078 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11079 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11080
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11081 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11082 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11083 If @code{numbers-list} is empty, do nothing. But if it has content,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11084 construct a list combining the square of the first number in the list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11085 with the result of the recursive call.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11086
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11087 (The example follows the pattern exactly: @code{nil} is returned if
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11088 the numbers' list is empty. In practice, you would write the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11089 conditional so it carries out the action when the numbers' list is not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11090 empty.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11091
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11092 The @code{print-elements-recursively} function (@pxref{Recursion with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11093 list, , Recursion with a List}) is another example of an @code{every}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11094 pattern, except in this case, rather than bring the results together
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11095 using @code{cons}, we print each element of output.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11096
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11097 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11098 The @code{print-elements-recursively} function looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11099
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11100 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11101 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11102 (setq animals '(gazelle giraffe lion tiger))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11103 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11104
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11105 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11106 (defun print-elements-recursively (list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11107 "Print each element of LIST on a line of its own.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11108 Uses recursion."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11109 (if list ; @r{do-again-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11110 (progn
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11111 (print (car list)) ; @r{body}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11112 (print-elements-recursively ; @r{recursive call}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11113 (cdr list))))) ; @r{next-step-expression}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11114
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11115 (print-elements-recursively animals)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11116 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11117 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11118
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11119 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11120 The pattern for @code{print-elements-recursively} is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11121
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11122 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11123 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11124 If the list be empty, do nothing.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11125 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11126 But if the list has at least one element,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11127 @itemize @minus
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11128 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11129 act on the beginning of the list (the @sc{car} of the list),
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11130 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11131 and make a recursive call on the rest (the @sc{cdr}) of the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11132 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11133 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11134
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11135 @node Accumulate, Keep, Every, Recursive Patterns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11136 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11137 @unnumberedsubsubsec Recursive Pattern: @emph{accumulate}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11138 @cindex Accumulate, type of recursive pattern
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11139 @cindex Recursive pattern: accumulate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11140
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11141 Another recursive pattern is called the @code{accumulate} pattern. In
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11142 the @code{accumulate} recursive pattern, an action is performed on
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11143 every element of a list and the result of that action is accumulated
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11144 with the results of performing the action on the other elements.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11145
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11146 This is very like the `every' pattern using @code{cons}, except that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11147 @code{cons} is not used, but some other combiner.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11148
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11149 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11150 The pattern is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11151
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11152 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11153 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11154 If a list be empty, return zero or some other constant.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11155 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11156 Else, act on the beginning of the list (the @sc{car} of the list),
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11157 @itemize @minus
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11158 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11159 and combine that acted-on element, using @code{+} or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11160 some other combining function, with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11161 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11162 a recursive call by the function on the rest (the @sc{cdr}) of the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11163 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11164 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11165
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11166 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11167 Here is an example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11168
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11169 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11170 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11171 (defun add-elements (numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11172 "Add the elements of NUMBERS-LIST together."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11173 (if (not numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11174 0
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11175 (+ (car numbers-list) (add-elements (cdr numbers-list)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11176 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11177
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11178 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11179 (add-elements '(1 2 3 4))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11180 @result{} 10
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11181 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11182 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11183
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11184 @xref{Files List, , Making a List of Files}, for an example of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11185 accumulate pattern.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11186
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11187 @node Keep, , Accumulate, Recursive Patterns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11188 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11189 @unnumberedsubsubsec Recursive Pattern: @emph{keep}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11190 @cindex Keep, type of recursive pattern
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11191 @cindex Recursive pattern: keep
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11192
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11193 A third recursive pattern is called the @code{keep} pattern.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11194 In the @code{keep} recursive pattern, each element of a list is tested;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11195 the element is acted on and the results are kept only if the element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11196 meets a criterion.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11197
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11198 Again, this is very like the `every' pattern, except the element is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11199 skipped unless it meets a criterion.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11201 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11202 The pattern has three parts:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11203
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11204 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11205 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11206 If a list be empty, return @code{nil}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11207 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11208 Else, if the beginning of the list (the @sc{car} of the list) passes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11209 a test
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11210 @itemize @minus
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11211 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11212 act on that element and combine it, using @code{cons} with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11213 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11214 a recursive call by the function on the rest (the @sc{cdr}) of the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11215 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11216 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11217 Otherwise, if the beginning of the list (the @sc{car} of the list) fails
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11218 the test
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11219 @itemize @minus
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11220 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11221 skip on that element,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11222 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11223 and, recursively call the function on the rest (the @sc{cdr}) of the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11224 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11225 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11226
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11227 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11228 Here is an example that uses @code{cond}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11229
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11230 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11231 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11232 (defun keep-three-letter-words (word-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11233 "Keep three letter words in WORD-LIST."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11234 (cond
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11235 ;; First do-again-test: stop-condition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11236 ((not word-list) nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11237
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11238 ;; Second do-again-test: when to act
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11239 ((eq 3 (length (symbol-name (car word-list))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11240 ;; combine acted-on element with recursive call on shorter list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11241 (cons (car word-list) (keep-three-letter-words (cdr word-list))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11242
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11243 ;; Third do-again-test: when to skip element;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11244 ;; recursively call shorter list with next-step expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11245 (t (keep-three-letter-words (cdr word-list)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11246 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11247
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11248 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11249 (keep-three-letter-words '(one two three four five six))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11250 @result{} (one two six)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11251 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11252 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11253
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11254 It goes without saying that you need not use @code{nil} as the test for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11255 when to stop; and you can, of course, combine these patterns.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11256
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11257 @node No Deferment, No deferment solution, Recursive Patterns, Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11258 @subsection Recursion without Deferments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11259 @cindex Deferment in recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11260 @cindex Recursion without Deferments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11261
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11262 Let's consider again what happens with the @code{triangle-recursively}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11263 function. We will find that the intermediate calculations are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11264 deferred until all can be done.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11265
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11266 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11267 Here is the function definition:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11268
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11269 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11270 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11271 (defun triangle-recursively (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11272 "Return the sum of the numbers 1 through NUMBER inclusive.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11273 Uses recursion."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11274 (if (= number 1) ; @r{do-again-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11275 1 ; @r{then-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11276 (+ number ; @r{else-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11277 (triangle-recursively ; @r{recursive call}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11278 (1- number))))) ; @r{next-step-expression}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11279 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11280 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11281
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11282 What happens when we call this function with a argument of 7?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11283
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11284 The first instance of the @code{triangle-recursively} function adds
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11285 the number 7 to the value returned by a second instance of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11286 @code{triangle-recursively}, an instance that has been passed an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11287 argument of 6. That is to say, the first calculation is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11288
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11289 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11290 (+ 7 (triangle-recursively 6)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11291 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11292
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11293 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11294 The first instance of @code{triangle-recursively}---you may want to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11295 think of it as a little robot---cannot complete its job. It must hand
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11296 off the calculation for @code{(triangle-recursively 6)} to a second
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11297 instance of the program, to a second robot. This second individual is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11298 completely different from the first one; it is, in the jargon, a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11299 `different instantiation'. Or, put another way, it is a different
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11300 robot. It is the same model as the first; it calculates triangle
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11301 numbers recursively; but it has a different serial number.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11302
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11303 And what does @code{(triangle-recursively 6)} return? It returns the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11304 number 6 added to the value returned by evaluating
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11305 @code{triangle-recursively} with an argument of 5. Using the robot
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11306 metaphor, it asks yet another robot to help it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11307
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11308 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11309 Now the total is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11310
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11311 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11312 (+ 7 6 (triangle-recursively 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11313 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11314
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11315 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11316 And what happens next?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11317
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11318 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11319 (+ 7 6 5 (triangle-recursively 4)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11320 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11321
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11322 Each time @code{triangle-recursively} is called, except for the last
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11323 time, it creates another instance of the program---another robot---and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11324 asks it to make a calculation.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11325
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11326 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11327 Eventually, the full addition is set up and performed:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11328
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11329 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11330 (+ 7 6 5 4 3 2 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11331 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11332
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11333 This design for the function defers the calculation of the first step
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11334 until the second can be done, and defers that until the third can be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11335 done, and so on. Each deferment means the computer must remember what
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11336 is being waited on. This is not a problem when there are only a few
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11337 steps, as in this example. But it can be a problem when there are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11338 more steps.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11339
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11340 @node No deferment solution, , No Deferment, Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11341 @subsection No Deferment Solution
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11342 @cindex No deferment solution
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11343 @cindex Defermentless solution
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11344 @cindex Solution without deferment
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11345
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11346 The solution to the problem of deferred operations is to write in a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11347 manner that does not defer operations@footnote{The phrase @dfn{tail
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11348 recursive} is used to describe such a process, one that uses
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11349 `constant space'.}. This requires
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11350 writing to a different pattern, often one that involves writing two
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11351 function definitions, an `initialization' function and a `helper'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11352 function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11353
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11354 The `initialization' function sets up the job; the `helper' function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11355 does the work.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11356
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11357 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11358 Here are the two function definitions for adding up numbers. They are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11359 so simple, I find them hard to understand.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11360
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11361 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11362 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11363 (defun triangle-initialization (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11364 "Return the sum of the numbers 1 through NUMBER inclusive.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11365 This is the `initialization' component of a two function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11366 duo that uses recursion."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11367 (triangle-recursive-helper 0 0 number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11368 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11369 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11370
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11371 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11372 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11373 (defun triangle-recursive-helper (sum counter number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11374 "Return SUM, using COUNTER, through NUMBER inclusive.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11375 This is the `helper' component of a two function duo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11376 that uses recursion."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11377 (if (> counter number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11378 sum
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11379 (triangle-recursive-helper (+ sum counter) ; @r{sum}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11380 (1+ counter) ; @r{counter}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11381 number))) ; @r{number}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11382 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11383 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11384
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11385 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11386 Install both function definitions by evaluating them, then call
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11387 @code{triangle-initialization} with 2 rows:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11388
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11389 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11390 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11391 (triangle-initialization 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11392 @result{} 3
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11393 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11394 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11395
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11396 The `initialization' function calls the first instance of the `helper'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11397 function with three arguments: zero, zero, and a number which is the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11398 number of rows in the triangle.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11399
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11400 The first two arguments passed to the `helper' function are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11401 initialization values. These values are changed when
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11402 @code{triangle-recursive-helper} invokes new instances.@footnote{The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11403 jargon is mildly confusing: @code{triangle-recursive-helper} uses a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11404 process that is iterative in a procedure that is recursive. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11405 process is called iterative because the computer need only record the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11406 three values, @code{sum}, @code{counter}, and @code{number}; the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11407 procedure is recursive because the function `calls itself'. On the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11408 other hand, both the process and the procedure used by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11409 @code{triangle-recursively} are called recursive. The word
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11410 `recursive' has different meanings in the two contexts.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11411
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11412 Let's see what happens when we have a triangle that has one row. (This
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11413 triangle will have one pebble in it!)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11414
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11415 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11416 @code{triangle-initialization} will call its helper with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11417 the arguments @w{@code{0 0 1}}. That function will run the conditional
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11418 test whether @code{(> counter number)}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11419
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11420 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11421 (> 0 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11422 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11423
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11424 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11425 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11426 and find that the result is false, so it will invoke
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11427 the then-part of the @code{if} clause:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11428
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11429 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11430 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11431 (triangle-recursive-helper
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11432 (+ sum counter) ; @r{sum plus counter} @result{} @r{sum}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11433 (1+ counter) ; @r{increment counter} @result{} @r{counter}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11434 number) ; @r{number stays the same}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11435 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11436 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11437
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11438 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11439 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11440 which will first compute:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11441
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11442 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11443 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11444 (triangle-recursive-helper (+ 0 0) ; @r{sum}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11445 (1+ 0) ; @r{counter}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11446 1) ; @r{number}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11447 @exdent which is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11448
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11449 (triangle-recursive-helper 0 1 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11450 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11451 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11452
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11453 Again, @code{(> counter number)} will be false, so again, the Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11454 interpreter will evaluate @code{triangle-recursive-helper}, creating a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11455 new instance with new arguments.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11456
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11457 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11458 This new instance will be;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11459
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11460 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11461 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11462 (triangle-recursive-helper
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11463 (+ sum counter) ; @r{sum plus counter} @result{} @r{sum}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11464 (1+ counter) ; @r{increment counter} @result{} @r{counter}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11465 number) ; @r{number stays the same}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11466
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11467 @exdent which is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11468
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11469 (triangle-recursive-helper 1 2 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11470 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11471 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11472
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11473 In this case, the @code{(> counter number)} test will be true! So the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11474 instance will return the value of the sum, which will be 1, as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11475 expected.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11476
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11477 Now, let's pass @code{triangle-initialization} an argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11478 of 2, to find out how many pebbles there are in a triangle with two rows.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11479
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11480 That function calls @code{(triangle-recursive-helper 0 0 2)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11481
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11482 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11483 In stages, the instances called will be:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11484
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11485 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11486 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11487 @r{sum counter number}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11488 (triangle-recursive-helper 0 1 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11489
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11490 (triangle-recursive-helper 1 2 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11491
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11492 (triangle-recursive-helper 3 3 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11493 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11494 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11495
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11496 When the last instance is called, the @code{(> counter number)} test
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11497 will be true, so the instance will return the value of @code{sum},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11498 which will be 3.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11499
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11500 This kind of pattern helps when you are writing functions that can use
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11501 many resources in a computer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11502
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11503 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11504 @node Looping exercise, , Recursion, Loops & Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11505 @section Looping Exercise
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11506
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11507 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11508 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11509 Write a function similar to @code{triangle} in which each row has a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11510 value which is the square of the row number. Use a @code{while} loop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11511
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11512 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11513 Write a function similar to @code{triangle} that multiplies instead of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11514 adds the values.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11515
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11516 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11517 Rewrite these two functions recursively. Rewrite these functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11518 using @code{cond}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11519
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11520 @c comma in printed title causes problem in Info cross reference
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11521 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11522 Write a function for Texinfo mode that creates an index entry at the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11523 beginning of a paragraph for every @samp{@@dfn} within the paragraph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11524 (In a Texinfo file, @samp{@@dfn} marks a definition. For more
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11525 information, see
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11526 @ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11527 @ref{Indicating, , Indicating Definitions, texinfo}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11528 @end ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11529 @ifhtml
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11530 @ref{Indicating, , Indicating, texinfo, Texinfo Manual}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11531 @end ifhtml
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11532 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11533 ``Indicating Definitions, Commands, etc.'' in @cite{Texinfo, The GNU
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11534 Documentation Format}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11535 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11536 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11537
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11538 @node Regexp Search, Counting Words, Loops & Recursion, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11539 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11540 @chapter Regular Expression Searches
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11541 @cindex Searches, illustrating
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11542 @cindex Regular expression searches
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11543 @cindex Patterns, searching for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11544 @cindex Motion by sentence and paragraph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11545 @cindex Sentences, movement by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11546 @cindex Paragraphs, movement by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11547
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11548 Regular expression searches are used extensively in GNU Emacs. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11549 two functions, @code{forward-sentence} and @code{forward-paragraph},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11550 illustrate these searches well. They use regular expressions to find
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11551 where to move point. The phrase `regular expression' is often written
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11552 as `regexp'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11553
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11554 Regular expression searches are described in @ref{Regexp Search, ,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11555 Regular Expression Search, emacs, The GNU Emacs Manual}, as well as in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11556 @ref{Regular Expressions, , , elisp, The GNU Emacs Lisp Reference
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11557 Manual}. In writing this chapter, I am presuming that you have at
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11558 least a mild acquaintance with them. The major point to remember is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11559 that regular expressions permit you to search for patterns as well as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11560 for literal strings of characters. For example, the code in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11561 @code{forward-sentence} searches for the pattern of possible
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11562 characters that could mark the end of a sentence, and moves point to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11563 that spot.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11564
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11565 Before looking at the code for the @code{forward-sentence} function, it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11566 is worth considering what the pattern that marks the end of a sentence
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11567 must be. The pattern is discussed in the next section; following that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11568 is a description of the regular expression search function,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11569 @code{re-search-forward}. The @code{forward-sentence} function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11570 is described in the section following. Finally, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11571 @code{forward-paragraph} function is described in the last section of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11572 this chapter. @code{forward-paragraph} is a complex function that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11573 introduces several new features.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11574
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11575 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11576 * sentence-end:: The regular expression for @code{sentence-end}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11577 * re-search-forward:: Very similar to @code{search-forward}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11578 * forward-sentence:: A straightforward example of regexp search.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11579 * forward-paragraph:: A somewhat complex example.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11580 * etags:: How to create your own @file{TAGS} table.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11581 * Regexp Review::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11582 * re-search Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11583 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11584
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11585 @node sentence-end, re-search-forward, Regexp Search, Regexp Search
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11586 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11587 @section The Regular Expression for @code{sentence-end}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11588 @findex sentence-end
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11589
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11590 The symbol @code{sentence-end} is bound to the pattern that marks the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11591 end of a sentence. What should this regular expression be?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11592
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11593 Clearly, a sentence may be ended by a period, a question mark, or an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11594 exclamation mark. Indeed, only clauses that end with one of those three
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11595 characters should be considered the end of a sentence. This means that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11596 the pattern should include the character set:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11597
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11598 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11599 [.?!]
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11600 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11601
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11602 However, we do not want @code{forward-sentence} merely to jump to a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11603 period, a question mark, or an exclamation mark, because such a character
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11604 might be used in the middle of a sentence. A period, for example, is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11605 used after abbreviations. So other information is needed.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11606
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11607 According to convention, you type two spaces after every sentence, but
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11608 only one space after a period, a question mark, or an exclamation mark in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11609 the body of a sentence. So a period, a question mark, or an exclamation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11610 mark followed by two spaces is a good indicator of an end of sentence.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11611 However, in a file, the two spaces may instead be a tab or the end of a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11612 line. This means that the regular expression should include these three
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11613 items as alternatives.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11614
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11615 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11616 This group of alternatives will look like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11617
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11618 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11619 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11620 \\($\\| \\| \\)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11621 ^ ^^
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11622 TAB SPC
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11623 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11624 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11625
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11626 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11627 Here, @samp{$} indicates the end of the line, and I have pointed out
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11628 where the tab and two spaces are inserted in the expression. Both are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11629 inserted by putting the actual characters into the expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11630
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11631 Two backslashes, @samp{\\}, are required before the parentheses and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11632 vertical bars: the first backslash quotes the following backslash in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11633 Emacs; and the second indicates that the following character, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11634 parenthesis or the vertical bar, is special.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11635
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11636 @need 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11637 Also, a sentence may be followed by one or more carriage returns, like
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11638 this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11639
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11640 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11641 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11642 [
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11643 ]*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11644 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11645 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11646
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11647 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11648 Like tabs and spaces, a carriage return is inserted into a regular
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11649 expression by inserting it literally. The asterisk indicates that the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11650 @key{RET} is repeated zero or more times.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11651
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11652 But a sentence end does not consist only of a period, a question mark or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11653 an exclamation mark followed by appropriate space: a closing quotation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11654 mark or a closing brace of some kind may precede the space. Indeed more
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11655 than one such mark or brace may precede the space. These require a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11656 expression that looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11657
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11658 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11659 []\"')@}]*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11660 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11661
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11662 In this expression, the first @samp{]} is the first character in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11663 expression; the second character is @samp{"}, which is preceded by a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11664 @samp{\} to tell Emacs the @samp{"} is @emph{not} special. The last
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11665 three characters are @samp{'}, @samp{)}, and @samp{@}}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11666
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11667 All this suggests what the regular expression pattern for matching the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11668 end of a sentence should be; and, indeed, if we evaluate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11669 @code{sentence-end} we find that it returns the following value:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11670
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11671 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11672 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11673 sentence-end
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11674 @result{} "[.?!][]\"')@}]*\\($\\| \\| \\)[
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11675 ]*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11676 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11677 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11678
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11679 @ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11680
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11681 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11682 (Note that here the @key{TAB}, two spaces, and @key{RET} are shown
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11683 literally in the pattern.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11684
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11685 This regular expression can be decyphered as follows:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11686
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11687 @table @code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11688 @item [.?!]
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11689 The first part of the pattern is the three characters, a period, a question
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11690 mark and an exclamation mark, within square brackets. The pattern must
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11691 begin with one or other of these characters.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11692
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11693 @item []\"')@}]*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11694 The second part of the pattern is the group of closing braces and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11695 quotation marks, which can appear zero or more times. These may follow
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11696 the period, question mark or exclamation mark. In a regular expression,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11697 the backslash, @samp{\}, followed by the double quotation mark,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11698 @samp{"}, indicates the class of string-quote characters. Usually, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11699 double quotation mark is the only character in this class. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11700 asterisk, @samp{*}, indicates that the items in the previous group (the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11701 group surrounded by square brackets, @samp{[]}) may be repeated zero or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11702 more times.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11703
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11704 @item \\($\\| \\| \\)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11705 The third part of the pattern is one or other of: either the end of a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11706 line, or two blank spaces, or a tab. The double back-slashes are used
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11707 to prevent Emacs from reading the parentheses and vertical bars as part
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11708 of the search pattern; the parentheses are used to mark the group and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11709 the vertical bars are used to indicated that the patterns to either side
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11710 of them are alternatives. The dollar sign is used to indicate the end
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11711 of a line and both the two spaces and the tab are each inserted as is to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11712 indicate what they are.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11713
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11714 @item [@key{RET}]*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11715 Finally, the last part of the pattern indicates that the end of the line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11716 or the whitespace following the period, question mark or exclamation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11717 mark may, but need not, be followed by one or more carriage returns. In
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11718 the pattern, the carriage return is inserted as an actual carriage
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11719 return between square brackets but here it is shown as @key{RET}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11720 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11721
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11722 @end ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11723
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11724 @node re-search-forward, forward-sentence, sentence-end, Regexp Search
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11725 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11726 @section The @code{re-search-forward} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11727 @findex re-search-forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11728
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11729 The @code{re-search-forward} function is very like the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11730 @code{search-forward} function. (@xref{search-forward, , The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11731 @code{search-forward} Function}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11732
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11733 @code{re-search-forward} searches for a regular expression. If the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11734 search is successful, it leaves point immediately after the last
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11735 character in the target. If the search is backwards, it leaves point
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11736 just before the first character in the target. You may tell
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11737 @code{re-search-forward} to return @code{t} for true. (Moving point
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11738 is therefore a `side effect'.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11739
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11740 Like @code{search-forward}, the @code{re-search-forward} function takes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11741 four arguments:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11742
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11743 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11744 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11745 The first argument is the regular expression that the function searches
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11746 for. The regular expression will be a string between quotations marks.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11747
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11748 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11749 The optional second argument limits how far the function will search; it is a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11750 bound, which is specified as a position in the buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11751
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11752 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11753 The optional third argument specifies how the function responds to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11754 failure: @code{nil} as the third argument causes the function to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11755 signal an error (and print a message) when the search fails; any other
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11756 value causes it to return @code{nil} if the search fails and @code{t}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11757 if the search succeeds.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11758
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11759 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11760 The optional fourth argument is the repeat count. A negative repeat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11761 count causes @code{re-search-forward} to search backwards.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11762 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11763
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11764 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11765 The template for @code{re-search-forward} looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11766
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11767 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11768 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11769 (re-search-forward "@var{regular-expression}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11770 @var{limit-of-search}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11771 @var{what-to-do-if-search-fails}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11772 @var{repeat-count})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11773 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11774 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11775
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11776 The second, third, and fourth arguments are optional. However, if you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11777 want to pass a value to either or both of the last two arguments, you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11778 must also pass a value to all the preceding arguments. Otherwise, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11779 Lisp interpreter will mistake which argument you are passing the value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11780 to.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11781
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11782 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11783 In the @code{forward-sentence} function, the regular expression will be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11784 the value of the variable @code{sentence-end}, namely:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11785
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11786 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11787 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11788 "[.?!][]\"')@}]*\\($\\| \\| \\)[
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11789 ]*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11790 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11791 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11792
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11793 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11794 The limit of the search will be the end of the paragraph (since a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11795 sentence cannot go beyond a paragraph). If the search fails, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11796 function will return @code{nil}; and the repeat count will be provided
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11797 by the argument to the @code{forward-sentence} function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11798
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11799 @node forward-sentence, forward-paragraph, re-search-forward, Regexp Search
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11800 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11801 @section @code{forward-sentence}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11802 @findex forward-sentence
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11803
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11804 The command to move the cursor forward a sentence is a straightforward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11805 illustration of how to use regular expression searches in Emacs Lisp.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11806 Indeed, the function looks longer and more complicated than it is; this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11807 is because the function is designed to go backwards as well as forwards;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11808 and, optionally, over more than one sentence. The function is usually
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11809 bound to the key command @kbd{M-e}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11810
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11811 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11812 * Complete forward-sentence::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11813 * fwd-sentence while loops:: Two @code{while} loops.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11814 * fwd-sentence re-search:: A regular expression search.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11815 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11816
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11817 @node Complete forward-sentence, fwd-sentence while loops, forward-sentence, forward-sentence
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11818 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11819 @unnumberedsubsec Complete @code{forward-sentence} function definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11820 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11821
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11822 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11823 Here is the code for @code{forward-sentence}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11824
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11825 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11826 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11827 (defun forward-sentence (&optional arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11828 "Move forward to next sentence-end. With argument, repeat.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11829 With negative argument, move backward repeatedly to sentence-beginning.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11830 Sentence ends are identified by the value of sentence-end
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11831 treated as a regular expression. Also, every paragraph boundary
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11832 terminates sentences as well."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11833 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11834 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11835 (interactive "p")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11836 (or arg (setq arg 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11837 (while (< arg 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11838 (let ((par-beg
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11839 (save-excursion (start-of-paragraph-text) (point))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11840 (if (re-search-backward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11841 (concat sentence-end "[^ \t\n]") par-beg t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11842 (goto-char (1- (match-end 0)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11843 (goto-char par-beg)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11844 (setq arg (1+ arg)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11845 (while (> arg 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11846 (let ((par-end
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11847 (save-excursion (end-of-paragraph-text) (point))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11848 (if (re-search-forward sentence-end par-end t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11849 (skip-chars-backward " \t\n")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11850 (goto-char par-end)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11851 (setq arg (1- arg))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11852 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11853 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11854
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11855 The function looks long at first sight and it is best to look at its
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11856 skeleton first, and then its muscle. The way to see the skeleton is to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11857 look at the expressions that start in the left-most columns:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11858
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11859 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11860 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11861 (defun forward-sentence (&optional arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11862 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11863 (interactive "p")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11864 (or arg (setq arg 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11865 (while (< arg 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11866 @var{body-of-while-loop}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11867 (while (> arg 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11868 @var{body-of-while-loop}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11869 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11870 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11871
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11872 This looks much simpler! The function definition consists of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11873 documentation, an @code{interactive} expression, an @code{or}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11874 expression, and @code{while} loops.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11875
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11876 Let's look at each of these parts in turn.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11877
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11878 We note that the documentation is thorough and understandable.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11879
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11880 The function has an @code{interactive "p"} declaration. This means
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11881 that the processed prefix argument, if any, is passed to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11882 function as its argument. (This will be a number.) If the function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11883 is not passed an argument (it is optional) then the argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11884 @code{arg} will be bound to 1. When @code{forward-sentence} is called
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11885 non-interactively without an argument, @code{arg} is bound to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11886 @code{nil}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11887
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11888 The @code{or} expression handles the prefix argument. What it does is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11889 either leave the value of @code{arg} as it is, but only if @code{arg}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11890 is bound to a value; or it sets the value of @code{arg} to 1, in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11891 case when @code{arg} is bound to @code{nil}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11892
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11893 @node fwd-sentence while loops, fwd-sentence re-search, Complete forward-sentence, forward-sentence
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11894 @unnumberedsubsec The @code{while} loops
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11895
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11896 Two @code{while} loops follow the @code{or} expression. The first
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11897 @code{while} has a true-or-false-test that tests true if the prefix
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11898 argument for @code{forward-sentence} is a negative number. This is for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11899 going backwards. The body of this loop is similar to the body of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11900 second @code{while} clause, but it is not exactly the same. We will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11901 skip this @code{while} loop and concentrate on the second @code{while}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11902 loop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11903
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11904 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11905 The second @code{while} loop is for moving point forward. Its skeleton
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11906 looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11907
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11908 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11909 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11910 (while (> arg 0) ; @r{true-or-false-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11911 (let @var{varlist}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11912 (if (@var{true-or-false-test})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11913 @var{then-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11914 @var{else-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11915 (setq arg (1- arg)))) ; @code{while} @r{loop decrementer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11916 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11917 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11918
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11919 The @code{while} loop is of the decrementing kind.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11920 (@xref{Decrementing Loop, , A Loop with a Decrementing Counter}.) It
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11921 has a true-or-false-test that tests true so long as the counter (in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11922 this case, the variable @code{arg}) is greater than zero; and it has a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11923 decrementer that subtracts 1 from the value of the counter every time
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11924 the loop repeats.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11925
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11926 If no prefix argument is given to @code{forward-sentence}, which is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11927 the most common way the command is used, this @code{while} loop will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11928 run once, since the value of @code{arg} will be 1.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11929
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11930 The body of the @code{while} loop consists of a @code{let} expression,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11931 which creates and binds a local variable, and has, as its body, an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11932 @code{if} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11933
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11934 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11935 The body of the @code{while} loop looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11936
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11937 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11938 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11939 (let ((par-end
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11940 (save-excursion (end-of-paragraph-text) (point))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11941 (if (re-search-forward sentence-end par-end t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11942 (skip-chars-backward " \t\n")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11943 (goto-char par-end)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11944 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11945 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11946
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11947 The @code{let} expression creates and binds the local variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11948 @code{par-end}. As we shall see, this local variable is designed to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11949 provide a bound or limit to the regular expression search. If the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11950 search fails to find a proper sentence ending in the paragraph, it will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11951 stop on reaching the end of the paragraph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11952
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11953 But first, let us examine how @code{par-end} is bound to the value of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11954 the end of the paragraph. What happens is that the @code{let} sets the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11955 value of @code{par-end} to the value returned when the Lisp interpreter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11956 evaluates the expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11957
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11958 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11959 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11960 (save-excursion (end-of-paragraph-text) (point))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11961 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11962 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11963
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11964 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11965 In this expression, @code{(end-of-paragraph-text)} moves point to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11966 end of the paragraph, @code{(point)} returns the value of point, and then
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11967 @code{save-excursion} restores point to its original position. Thus,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11968 the @code{let} binds @code{par-end} to the value returned by the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11969 @code{save-excursion} expression, which is the position of the end of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11970 the paragraph. (The @code{(end-of-paragraph-text)} function uses
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11971 @code{forward-paragraph}, which we will discuss shortly.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11972
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11973 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11974 Emacs next evaluates the body of the @code{let}, which is an @code{if}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11975 expression that looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11976
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11977 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11978 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11979 (if (re-search-forward sentence-end par-end t) ; @r{if-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11980 (skip-chars-backward " \t\n") ; @r{then-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11981 (goto-char par-end))) ; @r{else-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11982 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11983 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11984
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11985 The @code{if} tests whether its first argument is true and if so,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11986 evaluates its then-part; otherwise, the Emacs Lisp interpreter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11987 evaluates the else-part. The true-or-false-test of the @code{if}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11988 expression is the regular expression search.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11989
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11990 It may seem odd to have what looks like the `real work' of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11991 the @code{forward-sentence} function buried here, but this is a common
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11992 way this kind of operation is carried out in Lisp.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11993
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11994 @node fwd-sentence re-search, , fwd-sentence while loops, forward-sentence
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11995 @unnumberedsubsec The regular expression search
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11996
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11997 The @code{re-search-forward} function searches for the end of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11998 sentence, that is, for the pattern defined by the @code{sentence-end}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11999 regular expression. If the pattern is found---if the end of the sentence is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12000 found---then the @code{re-search-forward} function does two things:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12001
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12002 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12003 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12004 The @code{re-search-forward} function carries out a side effect, which
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12005 is to move point to the end of the occurrence found.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12006
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12007 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12008 The @code{re-search-forward} function returns a value of true. This is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12009 the value received by the @code{if}, and means that the search was
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12010 successful.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12011 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12012
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12013 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12014 The side effect, the movement of point, is completed before the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12015 @code{if} function is handed the value returned by the successful
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12016 conclusion of the search.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12017
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12018 When the @code{if} function receives the value of true from a successful
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12019 call to @code{re-search-forward}, the @code{if} evaluates the then-part,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12020 which is the expression @code{(skip-chars-backward " \t\n")}. This
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12021 expression moves backwards over any blank spaces, tabs or carriage
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12022 returns until a printed character is found and then leaves point after
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12023 the character. Since point has already been moved to the end of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12024 pattern that marks the end of the sentence, this action leaves point
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12025 right after the closing printed character of the sentence, which is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12026 usually a period.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12027
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12028 On the other hand, if the @code{re-search-forward} function fails to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12029 find a pattern marking the end of the sentence, the function returns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12030 false. The false then causes the @code{if} to evaluate its third
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12031 argument, which is @code{(goto-char par-end)}: it moves point to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12032 end of the paragraph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12033
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12034 Regular expression searches are exceptionally useful and the pattern
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12035 illustrated by @code{re-search-forward}, in which the search is the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12036 test of an @code{if} expression, is handy. You will see or write code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12037 incorporating this pattern often.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12038
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12039 @node forward-paragraph, etags, forward-sentence, Regexp Search
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12040 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12041 @section @code{forward-paragraph}: a Goldmine of Functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12042 @findex forward-paragraph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12043
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12044 The @code{forward-paragraph} function moves point forward to the end
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12045 of the paragraph. It is usually bound to @kbd{M-@}} and makes use of a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12046 number of functions that are important in themselves, including
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12047 @code{let*}, @code{match-beginning}, and @code{looking-at}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12048
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12049 The function definition for @code{forward-paragraph} is considerably
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12050 longer than the function definition for @code{forward-sentence}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12051 because it works with a paragraph, each line of which may begin with a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12052 fill prefix.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12053
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12054 A fill prefix consists of a string of characters that are repeated at
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12055 the beginning of each line. For example, in Lisp code, it is a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12056 convention to start each line of a paragraph-long comment with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12057 @samp{;;; }. In Text mode, four blank spaces make up another common
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12058 fill prefix, creating an indented paragraph. (@xref{Fill Prefix, , ,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12059 emacs, The GNU Emacs Manual}, for more information about fill
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12060 prefixes.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12061
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12062 The existence of a fill prefix means that in addition to being able to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12063 find the end of a paragraph whose lines begin on the left-most
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12064 column, the @code{forward-paragraph} function must be able to find the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12065 end of a paragraph when all or many of the lines in the buffer begin
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12066 with the fill prefix.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12067
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12068 Moreover, it is sometimes practical to ignore a fill prefix that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12069 exists, especially when blank lines separate paragraphs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12070 This is an added complication.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12071
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12072 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12073 * forward-paragraph in brief:: Key parts of the function definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12074 * fwd-para let:: The @code{let*} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12075 * fwd-para while:: The forward motion @code{while} loop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12076 * fwd-para between paragraphs:: Movement between paragraphs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12077 * fwd-para within paragraph:: Movement within paragraphs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12078 * fwd-para no fill prefix:: When there is no fill prefix.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12079 * fwd-para with fill prefix:: When there is a fill prefix.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12080 * fwd-para summary:: Summary of @code{forward-paragraph} code.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12081 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12082
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12083 @node forward-paragraph in brief, fwd-para let, forward-paragraph, forward-paragraph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12084 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12085 @unnumberedsubsec Shortened @code{forward-paragraph} function definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12086 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12087
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12088 Rather than print all of the @code{forward-paragraph} function, we
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12089 will only print parts of it. Read without preparation, the function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12090 can be daunting!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12091
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12092 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12093 In outline, the function looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12094
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12095 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12096 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12097 (defun forward-paragraph (&optional arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12098 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12099 (interactive "p")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12100 (or arg (setq arg 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12101 (let*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12102 @var{varlist}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12103 (while (< arg 0) ; @r{backward-moving-code}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12104 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12105 (setq arg (1+ arg)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12106 (while (> arg 0) ; @r{forward-moving-code}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12107 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12108 (setq arg (1- arg)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12109 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12110 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12111
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12112 The first parts of the function are routine: the function's argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12113 list consists of one optional argument. Documentation follows.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12114
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12115 The lower case @samp{p} in the @code{interactive} declaration means
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12116 that the processed prefix argument, if any, is passed to the function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12117 This will be a number, and is the repeat count of how many paragraphs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12118 point will move. The @code{or} expression in the next line handles
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12119 the common case when no argument is passed to the function, which occurs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12120 if the function is called from other code rather than interactively.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12121 This case was described earlier. (@xref{forward-sentence, The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12122 @code{forward-sentence} function}.) Now we reach the end of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12123 familiar part of this function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12124
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12125 @node fwd-para let, fwd-para while, forward-paragraph in brief, forward-paragraph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12126 @unnumberedsubsec The @code{let*} expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12127
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12128 The next line of the @code{forward-paragraph} function begins a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12129 @code{let*} expression. This is a different kind of expression than
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12130 we have seen so far. The symbol is @code{let*} not @code{let}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12131
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12132 The @code{let*} special form is like @code{let} except that Emacs sets
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12133 each variable in sequence, one after another, and variables in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12134 latter part of the varlist can make use of the values to which Emacs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12135 set variables in the earlier part of the varlist.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12136
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12137 In the @code{let*} expression in this function, Emacs binds two
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12138 variables: @code{fill-prefix-regexp} and @code{paragraph-separate}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12139 The value to which @code{paragraph-separate} is bound depends on the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12140 value of @code{fill-prefix-regexp}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12141
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12142 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12143 Let's look at each in turn. The symbol @code{fill-prefix-regexp} is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12144 set to the value returned by evaluating the following list:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12145
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12146 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12147 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12148 (and fill-prefix
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12149 (not (equal fill-prefix ""))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12150 (not paragraph-ignore-fill-prefix)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12151 (regexp-quote fill-prefix))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12152 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12153 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12154
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12155 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12156 This is an expression whose first element is the @code{and} special form.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12157
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12158 As we learned earlier (@pxref{kill-new function, , The @code{kill-new}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12159 function}), the @code{and} special form evaluates each of its
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12160 arguments until one of the arguments returns a value of @code{nil}, in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12161 which case the @code{and} expression returns @code{nil}; however, if
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12162 none of the arguments returns a value of @code{nil}, the value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12163 resulting from evaluating the last argument is returned. (Since such
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12164 a value is not @code{nil}, it is considered true in Lisp.) In other
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12165 words, an @code{and} expression returns a true value only if all its
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12166 arguments are true.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12167 @findex and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12168
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12169 In this case, the variable @code{fill-prefix-regexp} is bound to a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12170 non-@code{nil} value only if the following four expressions produce a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12171 true (i.e., a non-@code{nil}) value when they are evaluated; otherwise,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12172 @code{fill-prefix-regexp} is bound to @code{nil}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12173
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12174 @table @code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12175 @item fill-prefix
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12176 When this variable is evaluated, the value of the fill prefix, if any,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12177 is returned. If there is no fill prefix, this variable returns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12178 @code{nil}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12179
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12180 @item (not (equal fill-prefix "")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12181 This expression checks whether an existing fill prefix is an empty
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12182 string, that is, a string with no characters in it. An empty string is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12183 not a useful fill prefix.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12184
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12185 @item (not paragraph-ignore-fill-prefix)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12186 This expression returns @code{nil} if the variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12187 @code{paragraph-ignore-fill-prefix} has been turned on by being set to a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12188 true value such as @code{t}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12189
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12190 @item (regexp-quote fill-prefix)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12191 This is the last argument to the @code{and} special form. If all the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12192 arguments to the @code{and} are true, the value resulting from
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12193 evaluating this expression will be returned by the @code{and} expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12194 and bound to the variable @code{fill-prefix-regexp},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12195 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12196
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12197 @findex regexp-quote
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12198 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12199 The result of evaluating this @code{and} expression successfully is that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12200 @code{fill-prefix-regexp} will be bound to the value of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12201 @code{fill-prefix} as modified by the @code{regexp-quote} function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12202 What @code{regexp-quote} does is read a string and return a regular
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12203 expression that will exactly match the string and match nothing else.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12204 This means that @code{fill-prefix-regexp} will be set to a value that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12205 will exactly match the fill prefix if the fill prefix exists.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12206 Otherwise, the variable will be set to @code{nil}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12207
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12208 The second local variable in the @code{let*} expression is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12209 @code{paragraph-separate}. It is bound to the value returned by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12210 evaluating the expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12211
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12212 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12213 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12214 (if fill-prefix-regexp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12215 (concat paragraph-separate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12216 "\\|^" fill-prefix-regexp "[ \t]*$")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12217 paragraph-separate)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12218 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12219 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12220
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12221 This expression shows why @code{let*} rather than @code{let} was used.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12222 The true-or-false-test for the @code{if} depends on whether the variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12223 @code{fill-prefix-regexp} evaluates to @code{nil} or some other value.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12224
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12225 If @code{fill-prefix-regexp} does not have a value, Emacs evaluates
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12226 the else-part of the @code{if} expression and binds
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12227 @code{paragraph-separate} to its local value.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12228 (@code{paragraph-separate} is a regular expression that matches what
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12229 separates paragraphs.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12230
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12231 But if @code{fill-prefix-regexp} does have a value, Emacs evaluates
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12232 the then-part of the @code{if} expression and binds
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12233 @code{paragraph-separate} to a regular expression that includes the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12234 @code{fill-prefix-regexp} as part of the pattern.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12235
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12236 Specifically, @code{paragraph-separate} is set to the original value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12237 of the paragraph separate regular expression concatenated with an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12238 alternative expression that consists of the @code{fill-prefix-regexp}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12239 followed by a blank line. The @samp{^} indicates that the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12240 @code{fill-prefix-regexp} must begin a line, and the optional
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12241 whitespace to the end of the line is defined by @w{@code{"[ \t]*$"}}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12242 The @samp{\\|} defines this portion of the regexp as an alternative to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12243 @code{paragraph-separate}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12244
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12245 Now we get into the body of the @code{let*}. The first part of the body
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12246 of the @code{let*} deals with the case when the function is given a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12247 negative argument and is therefore moving backwards. We will skip this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12248 section.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12249
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12250 @node fwd-para while, fwd-para between paragraphs, fwd-para let, forward-paragraph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12251 @unnumberedsubsec The forward motion @code{while} loop
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12252
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12253 The second part of the body of the @code{let*} deals with forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12254 motion. It is a @code{while} loop that repeats itself so long as the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12255 value of @code{arg} is greater than zero. In the most common use of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12256 the function, the value of the argument is 1, so the body of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12257 @code{while} loop is evaluated exactly once, and the cursor moves
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12258 forward one paragraph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12259
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12260 This part handles three situations: when point is between paragraphs,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12261 when point is within a paragraph and there is a fill prefix, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12262 when point is within a paragraph and there is no fill prefix.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12263
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12264 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12265 The @code{while} loop looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12266
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12267 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12268 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12269 (while (> arg 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12270 (beginning-of-line)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12271
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12272 ;; @r{between paragraphs}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12273 (while (prog1 (and (not (eobp))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12274 (looking-at paragraph-separate))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12275 (forward-line 1)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12276 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12277
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12278 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12279 ;; @r{within paragraphs, with a fill prefix}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12280 (if fill-prefix-regexp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12281 ;; @r{There is a fill prefix; it overrides paragraph-start.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12282 (while (and (not (eobp))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12283 (not (looking-at paragraph-separate))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12284 (looking-at fill-prefix-regexp))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12285 (forward-line 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12286 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12287
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12288 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12289 ;; @r{within paragraphs, no fill prefix}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12290 (if (re-search-forward paragraph-start nil t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12291 (goto-char (match-beginning 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12292 (goto-char (point-max))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12293
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12294 (setq arg (1- arg)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12295 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12296 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12297
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12298 We can see immediately that this is a decrementing counter @code{while}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12299 loop, using the expression @code{(setq arg (1- arg))} as the decrementer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12300
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12301 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12302 The body of the loop consists of three expressions:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12303
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12304 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12305 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12306 ;; @r{between paragraphs}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12307 (beginning-of-line)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12308 (while
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12309 @var{body-of-while})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12310 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12311
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12312 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12313 ;; @r{within paragraphs, with fill prefix}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12314 (if @var{true-or-false-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12315 @var{then-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12316 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12317
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12318 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12319 ;; @r{within paragraphs, no fill prefix}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12320 @var{else-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12321 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12322 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12323
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12324 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12325 When the Emacs Lisp interpreter evaluates the body of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12326 @code{while} loop, the first thing it does is evaluate the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12327 @code{(beginning-of-line)} expression and move point to the beginning
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12328 of the line. Then there is an inner @code{while} loop. This
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12329 @code{while} loop is designed to move the cursor out of the blank
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12330 space between paragraphs, if it should happen to be there. Finally,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12331 there is an @code{if} expression that actually moves point to the end
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12332 of the paragraph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12333
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12334 @node fwd-para between paragraphs, fwd-para within paragraph, fwd-para while, forward-paragraph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12335 @unnumberedsubsec Between paragraphs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12336
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12337 First, let us look at the inner @code{while} loop. This loop handles
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12338 the case when point is between paragraphs; it uses three functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12339 that are new to us: @code{prog1}, @code{eobp} and @code{looking-at}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12340 @findex prog1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12341 @findex eobp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12342 @findex looking-at
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12343
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12344 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12345 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12346 @code{prog1} is similar to the @code{progn} special form,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12347 except that @code{prog1} evaluates its arguments in sequence and then
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12348 returns the value of its first argument as the value of the whole
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12349 expression. (@code{progn} returns the value of its last argument as the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12350 value of the expression.) The second and subsequent arguments to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12351 @code{prog1} are evaluated only for their side effects.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12352
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12353 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12354 @code{eobp} is an abbreviation of @samp{End Of Buffer P} and is a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12355 function that returns true if point is at the end of the buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12356
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12357 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12358 @code{looking-at} is a function that returns true if the text following
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12359 point matches the regular expression passed @code{looking-at} as its
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12360 argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12361 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12362
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12363 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12364 The @code{while} loop we are studying looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12365
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12366 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12367 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12368 (while (prog1 (and (not (eobp))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12369 (looking-at paragraph-separate))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12370 (forward-line 1)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12371 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12372 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12373
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12374 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12375 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12376 This is a @code{while} loop with no body! The true-or-false-test of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12377 loop is the expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12378
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12379 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12380 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12381 (prog1 (and (not (eobp))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12382 (looking-at paragraph-separate))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12383 (forward-line 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12384 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12385 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12386
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12387 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12388 The first argument to the @code{prog1} is the @code{and} expression. It
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12389 has within in it a test of whether point is at the end of the buffer and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12390 also a test of whether the pattern following point matches the regular
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12391 expression for separating paragraphs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12392
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12393 If the cursor is not at the end of the buffer and if the characters
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12394 following the cursor mark the separation between two paragraphs, then
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12395 the @code{and} expression is true. After evaluating the @code{and}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12396 expression, the Lisp interpreter evaluates the second argument to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12397 @code{prog1}, which is @code{forward-line}. This moves point forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12398 one line. The value returned by the @code{prog1} however, is the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12399 value of its first argument, so the @code{while} loop continues so
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12400 long as point is not at the end of the buffer and is between
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12401 paragraphs. When, finally, point is moved to a paragraph, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12402 @code{and} expression tests false. Note however, that the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12403 @code{forward-line} command is carried out anyhow. This means that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12404 when point is moved from between paragraphs to a paragraph, it is left
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12405 at the beginning of the second line of the paragraph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12406
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12407 @node fwd-para within paragraph, fwd-para no fill prefix, fwd-para between paragraphs, forward-paragraph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12408 @unnumberedsubsec Within paragraphs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12409
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12410 The next expression in the outer @code{while} loop is an @code{if}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12411 expression. The Lisp interpreter evaluates the then-part of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12412 @code{if} when the @code{fill-prefix-regexp} variable has a value other
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12413 than @code{nil}, and it evaluates the else-part when the value of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12414 @code{if fill-prefix-regexp} is @code{nil}, that is, when there is no
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12415 fill prefix.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12416
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12417 @node fwd-para no fill prefix, fwd-para with fill prefix, fwd-para within paragraph, forward-paragraph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12418 @unnumberedsubsec No fill prefix
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12419
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12420 It is simplest to look at the code for the case when there is no fill
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12421 prefix first. This code consists of yet another inner @code{if}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12422 expression, and reads as follows:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12423
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12424 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12425 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12426 (if (re-search-forward paragraph-start nil t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12427 (goto-char (match-beginning 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12428 (goto-char (point-max)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12429 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12430 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12431
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12432 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12433 This expression actually does the work that most people think of as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12434 the primary purpose of the @code{forward-paragraph} command: it causes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12435 a regular expression search to occur that searches forward to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12436 start of the next paragraph and if it is found, moves point there; but
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12437 if the start of another paragraph if not found, it moves point to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12438 end of the accessible region of the buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12439
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12440 The only unfamiliar part of this is the use of @code{match-beginning}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12441 This is another function that is new to us. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12442 @code{match-beginning} function returns a number specifying the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12443 location of the start of the text that was matched by the last regular
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12444 expression search.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12445
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12446 The @code{match-beginning} function is used here because of a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12447 characteristic of a forward search: a successful forward search,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12448 regardless of whether it is a plain search or a regular expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12449 search, will move point to the end of the text that is found. In this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12450 case, a successful search will move point to the end of the pattern for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12451 @code{paragraph-start}, which will be the beginning of the next
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12452 paragraph rather than the end of the current one.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12453
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12454 However, we want to put point at the end of the current paragraph, not at
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12455 the beginning of the next one. The two positions may be different,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12456 because there may be several blank lines between paragraphs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12457
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12458 @findex match-beginning
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12459 When given an argument of 0, @code{match-beginning} returns the position
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12460 that is the start of the text that the most recent regular
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12461 expression search matched. In this case, the most recent regular
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12462 expression search is the one looking for @code{paragraph-start}, so
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12463 @code{match-beginning} returns the beginning position of the pattern,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12464 rather than the end of the pattern. The beginning position is the end
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12465 of the paragraph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12466
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12467 (Incidentally, when passed a positive number as an argument, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12468 @code{match-beginning} function will place point at that parenthesized
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12469 expression in the last regular expression. It is a useful function.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12470
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12471 @node fwd-para with fill prefix, fwd-para summary, fwd-para no fill prefix, forward-paragraph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12472 @unnumberedsubsec With a fill prefix
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12473
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12474 The inner @code{if} expression just discussed is the else-part of an enclosing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12475 @code{if} expression which tests whether there is a fill prefix. If
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12476 there is a fill prefix, the then-part of this @code{if} is evaluated.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12477 It looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12478
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12479 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12480 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12481 (while (and (not (eobp))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12482 (not (looking-at paragraph-separate))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12483 (looking-at fill-prefix-regexp))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12484 (forward-line 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12485 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12486 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12487
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12488 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12489 What this expression does is move point forward line by line so long
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12490 as three conditions are true:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12491
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12492 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12493 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12494 Point is not at the end of the buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12495
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12496 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12497 The text following point does not separate paragraphs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12498
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12499 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12500 The pattern following point is the fill prefix regular expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12501 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12502
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12503 The last condition may be puzzling, until you remember that point was
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12504 moved to the beginning of the line early in the @code{forward-paragraph}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12505 function. This means that if the text has a fill prefix, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12506 @code{looking-at} function will see it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12507
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12508 @node fwd-para summary, , fwd-para with fill prefix, forward-paragraph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12509 @unnumberedsubsec Summary
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12510
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12511 In summary, when moving forward, the @code{forward-paragraph} function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12512 does the following:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12513
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12514 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12515 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12516 Move point to the beginning of the line.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12517
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12518 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12519 Skip over lines between paragraphs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12520
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12521 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12522 Check whether there is a fill prefix, and if there is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12523
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12524 @itemize ---
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12525
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12526 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12527 Go forward line by line so long as the line is not a paragraph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12528 separating line.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12529 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12530
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12531 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12532 But if there is no fill prefix,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12533
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12534 @itemize ---
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12535
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12536 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12537 Search for the next paragraph start pattern.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12538
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12539 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12540 Go to the beginning of the paragraph start pattern, which will be the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12541 end of the previous paragraph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12542
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12543 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12544 Or else go to the end of the accessible portion of the buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12545 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12546 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12547
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12548 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12549 For review, here is the code we have just been discussing, formatted
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12550 for clarity:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12551
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12552 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12553 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12554 (interactive "p")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12555 (or arg (setq arg 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12556 (let* (
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12557 (fill-prefix-regexp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12558 (and fill-prefix (not (equal fill-prefix ""))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12559 (not paragraph-ignore-fill-prefix)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12560 (regexp-quote fill-prefix)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12561 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12562
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12563 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12564 (paragraph-separate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12565 (if fill-prefix-regexp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12566 (concat paragraph-separate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12567 "\\|^"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12568 fill-prefix-regexp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12569 "[ \t]*$")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12570 paragraph-separate)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12571
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12572 @var{omitted-backward-moving-code} @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12573 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12574
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12575 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12576 (while (> arg 0) ; @r{forward-moving-code}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12577 (beginning-of-line)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12578
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12579 (while (prog1 (and (not (eobp))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12580 (looking-at paragraph-separate))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12581 (forward-line 1)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12582 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12583
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12584 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12585 (if fill-prefix-regexp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12586 (while (and (not (eobp)) ; @r{then-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12587 (not (looking-at paragraph-separate))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12588 (looking-at fill-prefix-regexp))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12589 (forward-line 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12590 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12591 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12592 ; @r{else-part: the inner-if}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12593 (if (re-search-forward paragraph-start nil t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12594 (goto-char (match-beginning 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12595 (goto-char (point-max))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12596
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12597 (setq arg (1- arg))))) ; @r{decrementer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12598 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12599 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12600
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12601 The full definition for the @code{forward-paragraph} function not only
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12602 includes this code for going forwards, but also code for going backwards.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12603
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12604 If you are reading this inside of GNU Emacs and you want to see the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12605 whole function, you can type @kbd{C-h f} (@code{describe-function})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12606 and the name of the function. This gives you the function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12607 documentation and the name of the library containing the function's
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12608 source. Place point over the name of the library and press the RET
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12609 key; you will be taken directly to the source. (Be sure to install
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12610 your sources! Without them, you are like a person who tries to drive
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12611 a car with his eyes shut!)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12612
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12613 @c !!! again, 21.0.100 tags table location in this paragraph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12614 Or -- a good habit to get into -- you can type @kbd{M-.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12615 (@code{find-tag}) and the name of the function when prompted for it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12616 This will take you directly to the source. If the @code{find-tag}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12617 function first asks you for the name of a @file{TAGS} table, give it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12618 the name of the @file{TAGS} file such as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12619 @file{/usr/local/share/emacs/21.0.100/lisp/TAGS}. (The exact path to your
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12620 @file{TAGS} file depends on how your copy of Emacs was installed.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12621
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12622 You can also create your own @file{TAGS} file for directories that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12623 lack one.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12624 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12625 @xref{etags, , Create Your Own @file{TAGS} File}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12626 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12627
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12628 @node etags, Regexp Review, forward-paragraph, Regexp Search
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12629 @section Create Your Own @file{TAGS} File
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12630 @findex etags
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12631 @cindex @file{TAGS} file, create own
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12632
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12633 The @kbd{M-.} (@code{find-tag}) command takes you directly to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12634 source for a function, variable, node, or other source. The function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12635 depends on tags tables to tell it where to go.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12636
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12637 You often need to build and install tags tables yourself. They are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12638 not built automatically. A tags table is called a @file{TAGS} file;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12639 the name is in upper case letters.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12640
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12641 You can create a @file{TAGS} file by calling the @code{etags} program
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12642 that comes as a part of the Emacs distribution. Usually, @code{etags}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12643 is compiled and installed when Emacs is built. (@code{etags} is not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12644 an Emacs Lisp function or a part of Emacs; it is a C program.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12645
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12646 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12647 To create a @file{TAGS} file, first switch to the directory in which
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12648 you want to create the file. In Emacs you can do this with the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12649 @kbd{M-x cd} command, or by visiting a file in the directory, or by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12650 listing the directory with @kbd{C-x d} (@code{dired}). Then run the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12651 compile command, with @w{@code{etags *.el}} as the command to execute
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12652
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12653 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12654 M-x compile RET etags *.el RET
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12655 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12656
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12657 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12658 to create a @file{TAGS} file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12659
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12660 For example, if you have a large number of files in your
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12661 @file{~/emacs} directory, as I do---I have 137 @file{.el} files in it,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12662 of which I load 12---you can create a @file{TAGS} file for the Emacs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12663 Lisp files in that directory.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12664
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12665 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12666 The @code{etags} program takes all the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12667 usual shell `wildcards'. For example, if you have two directories for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12668 which you want a single @file{TAGS file}, type
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12669 @w{@code{etags *.el ../elisp/*.el}},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12670 where @file{../elisp/} is the second directory:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12671
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12672 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12673 M-x compile RET etags *.el ../elisp/*.el RET
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12674 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12675
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12676 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12677 Type
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12678
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12679 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12680 M-x compile RET etags --help RET
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12681 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12682
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12683 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12684 to see a list of the options accepted by @code{etags} as well as a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12685 list of supported languages.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12686
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12687 The @code{etags} program handles more than 20 languages, including
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12688 Emacs Lisp, Common Lisp, Scheme, C, C++, Ada, Fortran, Java, LaTeX,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12689 Pascal, Perl, Python, Texinfo, makefiles, and most assemblers. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12690 program has no switches for specifying the language; it recognizes the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12691 language in an input file according to its file name and contents.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12692
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12693 @file{etags} is very helpful when you are writing code yourself and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12694 want to refer back to functions you have already written. Just run
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12695 @code{etags} again at intervals as you write new functions, so they
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12696 become part of the @file{TAGS} file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12697
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12698 If you think an appropriate @file{TAGS} file already exists for what
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12699 you want, but do not know where it is, you can use the @code{locate}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12700 program to attempt to find it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12701
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12702 Type @w{@kbd{M-x locate RET TAGS RET}} and Emacs will list for you the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12703 full path names of all your @file{TAGS} files. On my system, this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12704 command lists 34 @file{TAGS} files. On the other hand, a `plain
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12705 vanilla' system I recently installed did not contain any @file{TAGS}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12706 files.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12707
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12708 If the tags table you want has been created, you can use the @code{M-x
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12709 visit-tags-table} command to specify it. Otherwise, you will need to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12710 create the tag table yourself and then use @code{M-x
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12711 visit-tags-table}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12712
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12713 @subsubheading Building Tags in the Emacs sources
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12714 @cindex Building Tags in the Emacs sources
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12715 @cindex Tags in the Emacs sources
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12716 @findex make tags
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12717
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12718 The GNU Emacs sources come with a @file{Makefile} that contains a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12719 sophisticated @code{etags} command that creates, collects, and merges
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12720 tags tables from all over the Emacs sources and puts the information
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12721 into one @file{TAGS} file in the @file{src/} directory below the top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12722 level of your Emacs source directory.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12723
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12724 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12725 To build this @file{TAGS} file, go to the top level of your Emacs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12726 source directory and run the compile command @code{make tags}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12727
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12728 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12729 M-x compile RET make tags RET
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12730 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12731
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12732 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12733 (The @code{make tags} command works well with the GNU Emacs sources,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12734 as well as with some other source packages.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12735
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12736 For more information, see @ref{Tags, , Tag Tables, emacs, The GNU Emacs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12737 Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12738
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12739 @node Regexp Review, re-search Exercises, etags, Regexp Search
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12740 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12741 @section Review
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12742
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12743 Here is a brief summary of some recently introduced functions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12744
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12745 @table @code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12746 @item while
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12747 Repeatedly evaluate the body of the expression so long as the first
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12748 element of the body tests true. Then return @code{nil}. (The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12749 expression is evaluated only for its side effects.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12750
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12751 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12752 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12753
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12754 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12755 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12756 (let ((foo 2))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12757 (while (> foo 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12758 (insert (format "foo is %d.\n" foo))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12759 (setq foo (1- foo))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12760
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12761 @result{} foo is 2.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12762 foo is 1.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12763 nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12764 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12765 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12766 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12767 (The @code{insert} function inserts its arguments at point; the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12768 @code{format} function returns a string formatted from its arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12769 the way @code{message} formats its arguments; @code{\n} produces a new
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12770 line.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12771
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12772 @item re-search-forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12773 Search for a pattern, and if the pattern is found, move point to rest
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12774 just after it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12775
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12776 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12777 Takes four arguments, like @code{search-forward}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12778
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12779 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12780 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12781 A regular expression that specifies the pattern to search for.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12782
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12783 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12784 Optionally, the limit of the search.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12785
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12786 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12787 Optionally, what to do if the search fails, return @code{nil} or an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12788 error message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12789
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12790 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12791 Optionally, how many times to repeat the search; if negative, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12792 search goes backwards.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12793 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12794
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12795 @item let*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12796 Bind some variables locally to particular values,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12797 and then evaluate the remaining arguments, returning the value of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12798 last one. While binding the local variables, use the local values of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12799 variables bound earlier, if any.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12801 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12802 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12803
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12804 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12805 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12806 (let* ((foo 7)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12807 (bar (* 3 foo)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12808 (message "`bar' is %d." bar))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12809 @result{} `bar' is 21.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12810 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12811 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12812
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12813 @item match-beginning
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12814 Return the position of the start of the text found by the last regular
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12815 expression search.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12816
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12817 @item looking-at
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12818 Return @code{t} for true if the text after point matches the argument,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12819 which should be a regular expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12820
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12821 @item eobp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12822 Return @code{t} for true if point is at the end of the accessible part
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12823 of a buffer. The end of the accessible part is the end of the buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12824 if the buffer is not narrowed; it is the end of the narrowed part if
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12825 the buffer is narrowed.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12826
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12827 @item prog1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12828 Evaluate each argument in sequence and then return the value of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12829 @emph{first}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12830
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12831 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12832 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12833
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12834 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12835 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12836 (prog1 1 2 3 4)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12837 @result{} 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12838 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12839 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12840 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12841
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12842 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12843 @node re-search Exercises, , Regexp Review, Regexp Search
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12844 @section Exercises with @code{re-search-forward}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12845
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12846 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12847 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12848 Write a function to search for a regular expression that matches two
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12849 or more blank lines in sequence.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12850
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12851 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12852 Write a function to search for duplicated words, such as `the the'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12853 @xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12854 Manual}, for information on how to write a regexp (a regular
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12855 expression) to match a string that is composed of two identical
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12856 halves. You can devise several regexps; some are better than others.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12857 The function I use is described in an appendix, along with several
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12858 regexps. @xref{the-the, , @code{the-the} Duplicated Words Function}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12859 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12860
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12861 @node Counting Words, Words in a defun, Regexp Search, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12862 @chapter Counting: Repetition and Regexps
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12863 @cindex Repetition for word counting
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12864 @cindex Regular expressions for word counting
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12865
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12866 Repetition and regular expression searches are powerful tools that you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12867 often use when you write code in Emacs Lisp. This chapter illustrates
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12868 the use of regular expression searches through the construction of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12869 word count commands using @code{while} loops and recursion.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12870
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12871 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12872 * Why Count Words::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12873 * count-words-region:: Use a regexp, but find a problem.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12874 * recursive-count-words:: Start with case of no words in region.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12875 * Counting Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12876 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12877
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12878 @node Why Count Words, count-words-region, Counting Words, Counting Words
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12879 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12880 @unnumberedsec Counting words
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12881 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12882
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12883 The standard Emacs distribution contains a function for counting the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12884 number of lines within a region. However, there is no corresponding
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12885 function for counting words.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12886
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12887 Certain types of writing ask you to count words. Thus, if you write
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12888 an essay, you may be limited to 800 words; if you write a novel, you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12889 may discipline yourself to write 1000 words a day. It seems odd to me
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12890 that Emacs lacks a word count command. Perhaps people use Emacs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12891 mostly for code or types of documentation that do not require word
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12892 counts; or perhaps they restrict themselves to the operating system
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12893 word count command, @code{wc}. Alternatively, people may follow
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12894 the publishers' convention and compute a word count by dividing the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12895 number of characters in a document by five. In any event, here are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12896 commands to count words.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12897
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12898 @node count-words-region, recursive-count-words, Why Count Words, Counting Words
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12899 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12900 @section The @code{count-words-region} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12901 @findex count-words-region
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12902
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12903 A word count command could count words in a line, paragraph, region,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12904 or buffer. What should the command cover? You could design the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12905 command to count the number of words in a complete buffer. However,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12906 the Emacs tradition encourages flexibility---you may want to count
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12907 words in just a section, rather than all of a buffer. So it makes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12908 more sense to design the command to count the number of words in a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12909 region. Once you have a @code{count-words-region} command, you can,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12910 if you wish, count words in a whole buffer by marking it with @kbd{C-x
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12911 h} (@code{mark-whole-buffer}).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12912
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12913 Clearly, counting words is a repetitive act: starting from the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12914 beginning of the region, you count the first word, then the second
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12915 word, then the third word, and so on, until you reach the end of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12916 region. This means that word counting is ideally suited to recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12917 or to a @code{while} loop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12918
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12919 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12920 * Design count-words-region:: The definition using a @code{while} loop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12921 * Whitespace Bug:: The Whitespace Bug in @code{count-words-region}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12922 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12923
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12924 @node Design count-words-region, Whitespace Bug, count-words-region, count-words-region
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12925 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12926 @unnumberedsubsec Designing @code{count-words-region}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12927 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12928
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12929 First, we will implement the word count command with a @code{while}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12930 loop, then with recursion. The command will, of course, be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12931 interactive.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12932
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12933 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12934 The template for an interactive function definition is, as always:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12935
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12936 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12937 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12938 (defun @var{name-of-function} (@var{argument-list})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12939 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12940 (@var{interactive-expression}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12941 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12942 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12943 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12944
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12945 What we need to do is fill in the slots.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12946
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12947 The name of the function should be self-explanatory and similar to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12948 existing @code{count-lines-region} name. This makes the name easier
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12949 to remember. @code{count-words-region} is a good choice.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12950
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12951 The function counts words within a region. This means that the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12952 argument list must contain symbols that are bound to the two
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12953 positions, the beginning and end of the region. These two positions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12954 can be called @samp{beginning} and @samp{end} respectively. The first
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12955 line of the documentation should be a single sentence, since that is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12956 all that is printed as documentation by a command such as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12957 @code{apropos}. The interactive expression will be of the form
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12958 @samp{(interactive "r")}, since that will cause Emacs to pass the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12959 beginning and end of the region to the function's argument list. All
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12960 this is routine.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12961
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12962 The body of the function needs to be written to do three tasks:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12963 first, to set up conditions under which the @code{while} loop can
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12964 count words, second, to run the @code{while} loop, and third, to send
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12965 a message to the user.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12966
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12967 When a user calls @code{count-words-region}, point may be at the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12968 beginning or the end of the region. However, the counting process
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12969 must start at the beginning of the region. This means we will want
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12970 to put point there if it is not already there. Executing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12971 @code{(goto-char beginning)} ensures this. Of course, we will want to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12972 return point to its expected position when the function finishes its
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12973 work. For this reason, the body must be enclosed in a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12974 @code{save-excursion} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12975
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12976 The central part of the body of the function consists of a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12977 @code{while} loop in which one expression jumps point forward word by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12978 word, and another expression counts those jumps. The true-or-false-test
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12979 of the @code{while} loop should test true so long as point should jump
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12980 forward, and false when point is at the end of the region.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12981
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12982 We could use @code{(forward-word 1)} as the expression for moving point
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12983 forward word by word, but it is easier to see what Emacs identifies as a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12984 `word' if we use a regular expression search.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12985
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12986 A regular expression search that finds the pattern for which it is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12987 searching leaves point after the last character matched. This means
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12988 that a succession of successful word searches will move point forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12989 word by word.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12990
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12991 As a practical matter, we want the regular expression search to jump
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12992 over whitespace and punctuation between words as well as over the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12993 words themselves. A regexp that refuses to jump over interword
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12994 whitespace would never jump more than one word! This means that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12995 the regexp should include the whitespace and punctuation that follows
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12996 a word, if any, as well as the word itself. (A word may end a buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12997 and not have any following whitespace or punctuation, so that part of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12998 the regexp must be optional.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12999
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13000 Thus, what we want for the regexp is a pattern defining one or more
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13001 word constituent characters followed, optionally, by one or more
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13002 characters that are not word constituents. The regular expression for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13003 this is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13004
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13005 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13006 \w+\W*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13007 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13008
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13009 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13010 The buffer's syntax table determines which characters are and are not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13011 word constituents. (@xref{Syntax, , What Constitutes a Word or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13012 Symbol?}, for more about syntax. Also, see @ref{Syntax, Syntax, The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13013 Syntax Table, emacs, The GNU Emacs Manual}, and @ref{Syntax Tables, ,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13014 Syntax Tables, elisp, The GNU Emacs Lisp Reference Manual}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13015
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13016 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13017 The search expression looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13018
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13019 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13020 (re-search-forward "\\w+\\W*")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13021 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13022
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13023 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13024 (Note that paired backslashes precede the @samp{w} and @samp{W}. A
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13025 single backslash has special meaning to the Emacs Lisp interpreter. It
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13026 indicates that the following character is interpreted differently than
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13027 usual. For example, the two characters, @samp{\n}, stand for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13028 @samp{newline}, rather than for a backslash followed by @samp{n}. Two
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13029 backslashes in a row stand for an ordinary, `unspecial' backslash.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13030
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13031 We need a counter to count how many words there are; this variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13032 must first be set to 0 and then incremented each time Emacs goes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13033 around the @code{while} loop. The incrementing expression is simply:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13034
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13035 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13036 (setq count (1+ count))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13037 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13038
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13039 Finally, we want to tell the user how many words there are in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13040 region. The @code{message} function is intended for presenting this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13041 kind of information to the user. The message has to be phrased so
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13042 that it reads properly regardless of how many words there are in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13043 region: we don't want to say that ``there are 1 words in the region''.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13044 The conflict between singular and plural is ungrammatical. We can
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13045 solve this problem by using a conditional expression that evaluates
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13046 different messages depending on the number of words in the region.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13047 There are three possibilities: no words in the region, one word in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13048 region, and more than one word. This means that the @code{cond}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13049 special form is appropriate.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13050
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13051 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13052 All this leads to the following function definition:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13053
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13054 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13055 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13056 ;;; @r{First version; has bugs!}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13057 (defun count-words-region (beginning end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13058 "Print number of words in the region.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13059 Words are defined as at least one word-constituent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13060 character followed by at least one character that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13061 is not a word-constituent. The buffer's syntax
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13062 table determines which characters these are."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13063 (interactive "r")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13064 (message "Counting words in region ... ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13065 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13066
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13067 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13068 ;;; @r{1. Set up appropriate conditions.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13069 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13070 (goto-char beginning)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13071 (let ((count 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13072 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13073
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13074 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13075 ;;; @r{2. Run the} while @r{loop.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13076 (while (< (point) end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13077 (re-search-forward "\\w+\\W*")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13078 (setq count (1+ count)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13079 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13080
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13081 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13082 ;;; @r{3. Send a message to the user.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13083 (cond ((zerop count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13084 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13085 "The region does NOT have any words."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13086 ((= 1 count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13087 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13088 "The region has 1 word."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13089 (t
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13090 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13091 "The region has %d words." count))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13092 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13093 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13094
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13095 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13096 As written, the function works, but not in all circumstances.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13097
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13098 @node Whitespace Bug, , Design count-words-region, count-words-region
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13099 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13100 @subsection The Whitespace Bug in @code{count-words-region}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13101
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13102 The @code{count-words-region} command described in the preceding
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13103 section has two bugs, or rather, one bug with two manifestations.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13104 First, if you mark a region containing only whitespace in the middle
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13105 of some text, the @code{count-words-region} command tells you that the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13106 region contains one word! Second, if you mark a region containing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13107 only whitespace at the end of the buffer or the accessible portion of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13108 a narrowed buffer, the command displays an error message that looks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13109 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13110
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13111 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13112 Search failed: "\\w+\\W*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13113 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13114
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13115 If you are reading this in Info in GNU Emacs, you can test for these
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13116 bugs yourself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13117
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13118 First, evaluate the function in the usual manner to install it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13119 @ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13120 Here is a copy of the definition. Place your cursor after the closing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13121 parenthesis and type @kbd{C-x C-e} to install it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13122
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13123 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13124 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13125 ;; @r{First version; has bugs!}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13126 (defun count-words-region (beginning end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13127 "Print number of words in the region.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13128 Words are defined as at least one word-constituent character followed
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13129 by at least one character that is not a word-constituent. The buffer's
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13130 syntax table determines which characters these are."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13131 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13132 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13133 (interactive "r")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13134 (message "Counting words in region ... ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13135 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13136
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13137 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13138 ;;; @r{1. Set up appropriate conditions.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13139 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13140 (goto-char beginning)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13141 (let ((count 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13142 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13143
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13144 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13145 ;;; @r{2. Run the} while @r{loop.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13146 (while (< (point) end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13147 (re-search-forward "\\w+\\W*")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13148 (setq count (1+ count)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13149 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13150
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13151 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13152 ;;; @r{3. Send a message to the user.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13153 (cond ((zerop count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13154 (message "The region does NOT have any words."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13155 ((= 1 count) (message "The region has 1 word."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13156 (t (message "The region has %d words." count))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13157 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13158 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13159 @end ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13160
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13161 @need 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13162 If you wish, you can also install this keybinding by evaluating it:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13163
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13164 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13165 (global-set-key "\C-c=" 'count-words-region)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13166 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13167
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13168 To conduct the first test, set mark and point to the beginning and end
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13169 of the following line and then type @kbd{C-c =} (or @kbd{M-x
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13170 count-words-region} if you have not bound @kbd{C-c =}):
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13171
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13172 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13173 one two three
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13174 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13175
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13176 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13177 Emacs will tell you, correctly, that the region has three words.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13178
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13179 Repeat the test, but place mark at the beginning of the line and place
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13180 point just @emph{before} the word @samp{one}. Again type the command
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13181 @kbd{C-c =} (or @kbd{M-x count-words-region}). Emacs should tell you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13182 that the region has no words, since it is composed only of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13183 whitespace at the beginning of the line. But instead Emacs tells you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13184 that the region has one word!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13185
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13186 For the third test, copy the sample line to the end of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13187 @file{*scratch*} buffer and then type several spaces at the end of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13188 line. Place mark right after the word @samp{three} and point at the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13189 end of line. (The end of the line will be the end of the buffer.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13190 Type @kbd{C-c =} (or @kbd{M-x count-words-region}) as you did before.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13191 Again, Emacs should tell you that the region has no words, since it is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13192 composed only of the whitespace at the end of the line. Instead,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13193 Emacs displays an error message saying @samp{Search failed}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13194
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13195 The two bugs stem from the same problem.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13196
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13197 Consider the first manifestation of the bug, in which the command
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13198 tells you that the whitespace at the beginning of the line contains
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13199 one word. What happens is this: The @code{M-x count-words-region}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13200 command moves point to the beginning of the region. The @code{while}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13201 tests whether the value of point is smaller than the value of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13202 @code{end}, which it is. Consequently, the regular expression search
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13203 looks for and finds the first word. It leaves point after the word.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13204 @code{count} is set to one. The @code{while} loop repeats; but this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13205 time the value of point is larger than the value of @code{end}, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13206 loop is exited; and the function displays a message saying the number
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13207 of words in the region is one. In brief, the regular expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13208 search looks for and finds the word even though it is outside
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13209 the marked region.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13210
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13211 In the second manifestation of the bug, the region is whitespace at
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13212 the end of the buffer. Emacs says @samp{Search failed}. What happens
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13213 is that the true-or-false-test in the @code{while} loop tests true, so
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13214 the search expression is executed. But since there are no more words
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13215 in the buffer, the search fails.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13216
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13217 In both manifestations of the bug, the search extends or attempts to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13218 extend outside of the region.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13219
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13220 The solution is to limit the search to the region---this is a fairly
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13221 simple action, but as you may have come to expect, it is not quite as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13222 simple as you might think.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13223
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13224 As we have seen, the @code{re-search-forward} function takes a search
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13225 pattern as its first argument. But in addition to this first,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13226 mandatory argument, it accepts three optional arguments. The optional
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13227 second argument bounds the search. The optional third argument, if
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13228 @code{t}, causes the function to return @code{nil} rather than signal
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13229 an error if the search fails. The optional fourth argument is a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13230 repeat count. (In Emacs, you can see a function's documentation by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13231 typing @kbd{C-h f}, the name of the function, and then @key{RET}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13232
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13233 In the @code{count-words-region} definition, the value of the end of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13234 the region is held by the variable @code{end} which is passed as an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13235 argument to the function. Thus, we can add @code{end} as an argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13236 to the regular expression search expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13237
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13238 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13239 (re-search-forward "\\w+\\W*" end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13240 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13241
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13242 However, if you make only this change to the @code{count-words-region}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13243 definition and then test the new version of the definition on a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13244 stretch of whitespace, you will receive an error message saying
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13245 @samp{Search failed}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13246
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13247 What happens is this: the search is limited to the region, and fails
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13248 as you expect because there are no word-constituent characters in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13249 region. Since it fails, we receive an error message. But we do not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13250 want to receive an error message in this case; we want to receive the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13251 message that "The region does NOT have any words."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13252
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13253 The solution to this problem is to provide @code{re-search-forward}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13254 with a third argument of @code{t}, which causes the function to return
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13255 @code{nil} rather than signal an error if the search fails.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13256
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13257 However, if you make this change and try it, you will see the message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13258 ``Counting words in region ... '' and @dots{} you will keep on seeing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13259 that message @dots{}, until you type @kbd{C-g} (@code{keyboard-quit}).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13260
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13261 Here is what happens: the search is limited to the region, as before,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13262 and it fails because there are no word-constituent characters in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13263 region, as expected. Consequently, the @code{re-search-forward}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13264 expression returns @code{nil}. It does nothing else. In particular,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13265 it does not move point, which it does as a side effect if it finds the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13266 search target. After the @code{re-search-forward} expression returns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13267 @code{nil}, the next expression in the @code{while} loop is evaluated.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13268 This expression increments the count. Then the loop repeats. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13269 true-or-false-test tests true because the value of point is still less
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13270 than the value of end, since the @code{re-search-forward} expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13271 did not move point. @dots{} and the cycle repeats @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13272
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13273 The @code{count-words-region} definition requires yet another
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13274 modification, to cause the true-or-false-test of the @code{while} loop
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13275 to test false if the search fails. Put another way, there are two
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13276 conditions that must be satisfied in the true-or-false-test before the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13277 word count variable is incremented: point must still be within the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13278 region and the search expression must have found a word to count.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13279
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13280 Since both the first condition and the second condition must be true
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13281 together, the two expressions, the region test and the search
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13282 expression, can be joined with an @code{and} special form and embedded in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13283 the @code{while} loop as the true-or-false-test, like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13284
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13285 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13286 (and (< (point) end) (re-search-forward "\\w+\\W*" end t))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13287 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13288
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13289 @c colon in printed section title causes problem in Info cross reference
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13290 @c also trouble with an overfull hbox
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13291 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13292 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13293 (For information about @code{and}, see
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13294 @ref{forward-paragraph, , @code{forward-paragraph}: a Goldmine of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13295 Functions}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13296 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13297 @ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13298 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13299 (@xref{forward-paragraph}, for information about @code{and}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13300 @end ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13301
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13302 The @code{re-search-forward} expression returns @code{t} if the search
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13303 succeeds and as a side effect moves point. Consequently, as words are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13304 found, point is moved through the region. When the search
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13305 expression fails to find another word, or when point reaches the end
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13306 of the region, the true-or-false-test tests false, the @code{while}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13307 loop exists, and the @code{count-words-region} function displays one
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13308 or other of its messages.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13309
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13310 After incorporating these final changes, the @code{count-words-region}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13311 works without bugs (or at least, without bugs that I have found!).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13312 Here is what it looks like:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13313
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13314 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13315 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13316 ;;; @r{Final version:} @code{while}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13317 (defun count-words-region (beginning end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13318 "Print number of words in the region."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13319 (interactive "r")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13320 (message "Counting words in region ... ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13321 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13322
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13323 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13324 ;;; @r{1. Set up appropriate conditions.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13325 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13326 (let ((count 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13327 (goto-char beginning)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13328 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13329
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13330 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13331 ;;; @r{2. Run the} while @r{loop.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13332 (while (and (< (point) end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13333 (re-search-forward "\\w+\\W*" end t))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13334 (setq count (1+ count)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13335 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13336
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13337 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13338 ;;; @r{3. Send a message to the user.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13339 (cond ((zerop count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13340 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13341 "The region does NOT have any words."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13342 ((= 1 count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13343 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13344 "The region has 1 word."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13345 (t
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13346 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13347 "The region has %d words." count))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13348 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13349 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13350
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13351 @node recursive-count-words, Counting Exercise, count-words-region, Counting Words
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13352 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13353 @section Count Words Recursively
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13354 @cindex Count words recursively
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13355 @cindex Recursively counting words
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13356 @cindex Words, counted recursively
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13357
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13358 You can write the function for counting words recursively as well as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13359 with a @code{while} loop. Let's see how this is done.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13360
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13361 First, we need to recognize that the @code{count-words-region}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13362 function has three jobs: it sets up the appropriate conditions for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13363 counting to occur; it counts the words in the region; and it sends a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13364 message to the user telling how many words there are.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13365
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13366 If we write a single recursive function to do everything, we will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13367 receive a message for every recursive call. If the region contains 13
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13368 words, we will receive thirteen messages, one right after the other.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13369 We don't want this! Instead, we must write two functions to do the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13370 job, one of which (the recursive function) will be used inside of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13371 other. One function will set up the conditions and display the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13372 message; the other will return the word count.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13373
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13374 Let us start with the function that causes the message to be displayed.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13375 We can continue to call this @code{count-words-region}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13376
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13377 This is the function that the user will call. It will be interactive.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13378 Indeed, it will be similar to our previous versions of this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13379 function, except that it will call @code{recursive-count-words} to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13380 determine how many words are in the region.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13381
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13382 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13383 We can readily construct a template for this function, based on our
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13384 previous versions:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13385
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13386 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13387 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13388 ;; @r{Recursive version; uses regular expression search}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13389 (defun count-words-region (beginning end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13390 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13391 (@var{interactive-expression}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13392 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13393 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13394
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13395 ;;; @r{1. Set up appropriate conditions.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13396 (@var{explanatory message})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13397 (@var{set-up functions}@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13398 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13399 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13400
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13401 ;;; @r{2. Count the words.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13402 @var{recursive call}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13403 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13404 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13405
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13406 ;;; @r{3. Send a message to the user.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13407 @var{message providing word count}))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13408 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13409 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13410
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13411 The definition looks straightforward, except that somehow the count
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13412 returned by the recursive call must be passed to the message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13413 displaying the word count. A little thought suggests that this can be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13414 done by making use of a @code{let} expression: we can bind a variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13415 in the varlist of a @code{let} expression to the number of words in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13416 the region, as returned by the recursive call; and then the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13417 @code{cond} expression, using binding, can display the value to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13418 user.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13419
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13420 Often, one thinks of the binding within a @code{let} expression as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13421 somehow secondary to the `primary' work of a function. But in this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13422 case, what you might consider the `primary' job of the function,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13423 counting words, is done within the @code{let} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13424
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13425 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13426 Using @code{let}, the function definition looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13427
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13428 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13429 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13430 (defun count-words-region (beginning end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13431 "Print number of words in the region."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13432 (interactive "r")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13433 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13434
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13435 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13436 ;;; @r{1. Set up appropriate conditions.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13437 (message "Counting words in region ... ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13438 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13439 (goto-char beginning)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13440 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13441
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13442 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13443 ;;; @r{2. Count the words.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13444 (let ((count (recursive-count-words end)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13445 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13446
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13447 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13448 ;;; @r{3. Send a message to the user.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13449 (cond ((zerop count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13450 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13451 "The region does NOT have any words."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13452 ((= 1 count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13453 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13454 "The region has 1 word."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13455 (t
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13456 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13457 "The region has %d words." count))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13458 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13459 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13460
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13461 Next, we need to write the recursive counting function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13462
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13463 A recursive function has at least three parts: the `do-again-test', the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13464 `next-step-expression', and the recursive call.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13465
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13466 The do-again-test determines whether the function will or will not be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13467 called again. Since we are counting words in a region and can use a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13468 function that moves point forward for every word, the do-again-test
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13469 can check whether point is still within the region. The do-again-test
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13470 should find the value of point and determine whether point is before,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13471 at, or after the value of the end of the region. We can use the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13472 @code{point} function to locate point. Clearly, we must pass the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13473 value of the end of the region to the recursive counting function as an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13474 argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13475
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13476 In addition, the do-again-test should also test whether the search finds a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13477 word. If it does not, the function should not call itself again.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13478
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13479 The next-step-expression changes a value so that when the recursive
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13480 function is supposed to stop calling itself, it stops. More
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13481 precisely, the next-step-expression changes a value so that at the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13482 right time, the do-again-test stops the recursive function from
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13483 calling itself again. In this case, the next-step-expression can be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13484 the expression that moves point forward, word by word.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13485
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13486 The third part of a recursive function is the recursive call.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13487
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13488 Somewhere, also, we also need a part that does the `work' of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13489 function, a part that does the counting. A vital part!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13490
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13491 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13492 But already, we have an outline of the recursive counting function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13493
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13494 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13495 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13496 (defun recursive-count-words (region-end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13497 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13498 @var{do-again-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13499 @var{next-step-expression}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13500 @var{recursive call})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13501 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13502 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13503
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13504 Now we need to fill in the slots. Let's start with the simplest cases
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13505 first: if point is at or beyond the end of the region, there cannot
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13506 be any words in the region, so the function should return zero.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13507 Likewise, if the search fails, there are no words to count, so the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13508 function should return zero.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13509
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13510 On the other hand, if point is within the region and the search
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13511 succeeds, the function should call itself again.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13512
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13513 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13514 Thus, the do-again-test should look like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13515
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13516 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13517 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13518 (and (< (point) region-end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13519 (re-search-forward "\\w+\\W*" region-end t))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13520 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13521 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13522
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13523 Note that the search expression is part of the do-again-test---the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13524 function returns @code{t} if its search succeeds and @code{nil} if it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13525 fails. (@xref{Whitespace Bug, , The Whitespace Bug in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13526 @code{count-words-region}}, for an explanation of how
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13527 @code{re-search-forward} works.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13528
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13529 The do-again-test is the true-or-false test of an @code{if} clause.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13530 Clearly, if the do-again-test succeeds, the then-part of the @code{if}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13531 clause should call the function again; but if it fails, the else-part
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13532 should return zero since either point is outside the region or the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13533 search failed because there were no words to find.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13534
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13535 But before considering the recursive call, we need to consider the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13536 next-step-expression. What is it? Interestingly, it is the search
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13537 part of the do-again-test.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13538
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13539 In addition to returning @code{t} or @code{nil} for the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13540 do-again-test, @code{re-search-forward} moves point forward as a side
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13541 effect of a successful search. This is the action that changes the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13542 value of point so that the recursive function stops calling itself
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13543 when point completes its movement through the region. Consequently,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13544 the @code{re-search-forward} expression is the next-step-expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13545
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13546 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13547 In outline, then, the body of the @code{recursive-count-words}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13548 function looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13549
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13550 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13551 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13552 (if @var{do-again-test-and-next-step-combined}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13553 ;; @r{then}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13554 @var{recursive-call-returning-count}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13555 ;; @r{else}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13556 @var{return-zero})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13557 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13558 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13559
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13560 How to incorporate the mechanism that counts?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13561
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13562 If you are not used to writing recursive functions, a question like
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13563 this can be troublesome. But it can and should be approached
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13564 systematically.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13565
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13566 We know that the counting mechanism should be associated in some way
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13567 with the recursive call. Indeed, since the next-step-expression moves
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13568 point forward by one word, and since a recursive call is made for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13569 each word, the counting mechanism must be an expression that adds one
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13570 to the value returned by a call to @code{recursive-count-words}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13571
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13572 Consider several cases:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13573
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13574 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13575 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13576 If there are two words in the region, the function should return
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13577 a value resulting from adding one to the value returned when it counts
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13578 the first word, plus the number returned when it counts the remaining
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13579 words in the region, which in this case is one.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13580
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13581 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13582 If there is one word in the region, the function should return
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13583 a value resulting from adding one to the value returned when it counts
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13584 that word, plus the number returned when it counts the remaining
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13585 words in the region, which in this case is zero.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13586
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13587 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13588 If there are no words in the region, the function should return zero.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13589 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13590
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13591 From the sketch we can see that the else-part of the @code{if} returns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13592 zero for the case of no words. This means that the then-part of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13593 @code{if} must return a value resulting from adding one to the value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13594 returned from a count of the remaining words.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13595
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13596 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13597 The expression will look like this, where @code{1+} is a function that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13598 adds one to its argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13599
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13600 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13601 (1+ (recursive-count-words region-end))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13602 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13603
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13604 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13605 The whole @code{recursive-count-words} function will then look like
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13606 this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13607
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13608 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13609 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13610 (defun recursive-count-words (region-end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13611 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13612
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13613 ;;; @r{1. do-again-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13614 (if (and (< (point) region-end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13615 (re-search-forward "\\w+\\W*" region-end t))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13616 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13617
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13618 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13619 ;;; @r{2. then-part: the recursive call}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13620 (1+ (recursive-count-words region-end))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13621
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13622 ;;; @r{3. else-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13623 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13624 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13625 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13626
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13627 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13628 Let's examine how this works:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13629
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13630 If there are no words in the region, the else part of the @code{if}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13631 expression is evaluated and consequently the function returns zero.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13632
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13633 If there is one word in the region, the value of point is less than
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13634 the value of @code{region-end} and the search succeeds. In this case,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13635 the true-or-false-test of the @code{if} expression tests true, and the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13636 then-part of the @code{if} expression is evaluated. The counting
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13637 expression is evaluated. This expression returns a value (which will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13638 be the value returned by the whole function) that is the sum of one
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13639 added to the value returned by a recursive call.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13640
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13641 Meanwhile, the next-step-expression has caused point to jump over the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13642 first (and in this case only) word in the region. This means that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13643 when @code{(recursive-count-words region-end)} is evaluated a second
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13644 time, as a result of the recursive call, the value of point will be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13645 equal to or greater than the value of region end. So this time,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13646 @code{recursive-count-words} will return zero. The zero will be added
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13647 to one, and the original evaluation of @code{recursive-count-words}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13648 will return one plus zero, which is one, which is the correct amount.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13649
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13650 Clearly, if there are two words in the region, the first call to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13651 @code{recursive-count-words} returns one added to the value returned
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13652 by calling @code{recursive-count-words} on a region containing the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13653 remaining word---that is, it adds one to one, producing two, which is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13654 the correct amount.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13655
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13656 Similarly, if there are three words in the region, the first call to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13657 @code{recursive-count-words} returns one added to the value returned
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13658 by calling @code{recursive-count-words} on a region containing the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13659 remaining two words---and so on and so on.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13660
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13661 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13662 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13663 With full documentation the two functions look like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13664
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13665 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13666 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13667 The recursive function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13668
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13669 @findex recursive-count-words
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13670 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13671 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13672 (defun recursive-count-words (region-end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13673 "Number of words between point and REGION-END."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13674 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13675
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13676 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13677 ;;; @r{1. do-again-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13678 (if (and (< (point) region-end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13679 (re-search-forward "\\w+\\W*" region-end t))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13680 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13681
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13682 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13683 ;;; @r{2. then-part: the recursive call}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13684 (1+ (recursive-count-words region-end))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13685
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13686 ;;; @r{3. else-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13687 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13688 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13689 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13690
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13691 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13692 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13693 The wrapper:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13694
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13695 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13696 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13697 ;;; @r{Recursive version}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13698 (defun count-words-region (beginning end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13699 "Print number of words in the region.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13700 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13701
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13702 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13703 Words are defined as at least one word-constituent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13704 character followed by at least one character that is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13705 not a word-constituent. The buffer's syntax table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13706 determines which characters these are."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13707 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13708 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13709 (interactive "r")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13710 (message "Counting words in region ... ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13711 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13712 (goto-char beginning)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13713 (let ((count (recursive-count-words end)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13714 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13715 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13716 (cond ((zerop count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13717 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13718 "The region does NOT have any words."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13719 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13720 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13721 ((= 1 count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13722 (message "The region has 1 word."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13723 (t
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13724 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13725 "The region has %d words." count))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13726 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13727 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13728
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13729 @node Counting Exercise, , recursive-count-words, Counting Words
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13730 @section Exercise: Counting Punctuation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13731
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13732 Using a @code{while} loop, write a function to count the number of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13733 punctuation marks in a region---period, comma, semicolon, colon,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13734 exclamation mark, and question mark. Do the same using recursion.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13735
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13736 @node Words in a defun, Readying a Graph, Counting Words, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13737 @chapter Counting Words in a @code{defun}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13738 @cindex Counting words in a @code{defun}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13739 @cindex Word counting in a @code{defun}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13740
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13741 Our next project is to count the number of words in a function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13742 definition. Clearly, this can be done using some variant of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13743 @code{count-word-region}. @xref{Counting Words, , Counting Words:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13744 Repetition and Regexps}. If we are just going to count the words in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13745 one definition, it is easy enough to mark the definition with the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13746 @kbd{C-M-h} (@code{mark-defun}) command, and then call
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13747 @code{count-word-region}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13748
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13749 However, I am more ambitious: I want to count the words and symbols in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13750 every definition in the Emacs sources and then print a graph that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13751 shows how many functions there are of each length: how many contain 40
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13752 to 49 words or symbols, how many contain 50 to 59 words or symbols,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13753 and so on. I have often been curious how long a typical function is,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13754 and this will tell.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13755
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13756 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13757 * Divide and Conquer::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13758 * Words and Symbols:: What to count?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13759 * Syntax:: What constitutes a word or symbol?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13760 * count-words-in-defun:: Very like @code{count-words}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13761 * Several defuns:: Counting several defuns in a file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13762 * Find a File:: Do you want to look at a file?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13763 * lengths-list-file:: A list of the lengths of many definitions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13764 * Several files:: Counting in definitions in different files.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13765 * Several files recursively:: Recursively counting in different files.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13766 * Prepare the data:: Prepare the data for display in a graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13767 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13768
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13769 @node Divide and Conquer, Words and Symbols, Words in a defun, Words in a defun
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13770 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13771 @unnumberedsec Divide and Conquer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13772 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13773
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13774 Described in one phrase, the histogram project is daunting; but
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13775 divided into numerous small steps, each of which we can take one at a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13776 time, the project becomes less fearsome. Let us consider what the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13777 steps must be:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13778
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13779 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13780 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13781 First, write a function to count the words in one definition. This
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13782 includes the problem of handling symbols as well as words.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13783
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13784 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13785 Second, write a function to list the numbers of words in each function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13786 in a file. This function can use the @code{count-words-in-defun}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13787 function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13788
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13789 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13790 Third, write a function to list the numbers of words in each function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13791 in each of several files. This entails automatically finding the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13792 various files, switching to them, and counting the words in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13793 definitions within them.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13794
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13795 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13796 Fourth, write a function to convert the list of numbers that we
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13797 created in step three to a form that will be suitable for printing as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13798 a graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13799
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13800 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13801 Fifth, write a function to print the results as a graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13802 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13803
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13804 This is quite a project! But if we take each step slowly, it will not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13805 be difficult.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13806
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13807 @node Words and Symbols, Syntax, Divide and Conquer, Words in a defun
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13808 @section What to Count?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13809 @cindex Words and symbols in defun
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13810
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13811 When we first start thinking about how to count the words in a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13812 function definition, the first question is (or ought to be) what are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13813 we going to count? When we speak of `words' with respect to a Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13814 function definition, we are actually speaking, in large part, of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13815 `symbols'. For example, the following @code{multiply-by-seven}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13816 function contains the five symbols @code{defun},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13817 @code{multiply-by-seven}, @code{number}, @code{*}, and @code{7}. In
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13818 addition, in the documentation string, it contains the four words
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13819 @samp{Multiply}, @samp{NUMBER}, @samp{by}, and @samp{seven}. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13820 symbol @samp{number} is repeated, so the definition contains a total
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13821 of ten words and symbols.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13822
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13823 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13824 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13825 (defun multiply-by-seven (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13826 "Multiply NUMBER by seven."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13827 (* 7 number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13828 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13829 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13830
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13831 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13832 However, if we mark the @code{multiply-by-seven} definition with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13833 @kbd{C-M-h} (@code{mark-defun}), and then call
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13834 @code{count-words-region} on it, we will find that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13835 @code{count-words-region} claims the definition has eleven words, not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13836 ten! Something is wrong!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13837
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13838 The problem is twofold: @code{count-words-region} does not count the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13839 @samp{*} as a word, and it counts the single symbol,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13840 @code{multiply-by-seven}, as containing three words. The hyphens are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13841 treated as if they were interword spaces rather than intraword
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13842 connectors: @samp{multiply-by-seven} is counted as if it were written
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13843 @samp{multiply by seven}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13844
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13845 The cause of this confusion is the regular expression search within
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13846 the @code{count-words-region} definition that moves point forward word
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13847 by word. In the canonical version of @code{count-words-region}, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13848 regexp is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13849
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13850 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13851 "\\w+\\W*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13852 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13853
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13854 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13855 This regular expression is a pattern defining one or more word
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13856 constituent characters possibly followed by one or more characters
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13857 that are not word constituents. What is meant by `word constituent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13858 characters' brings us to the issue of syntax, which is worth a section
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13859 of its own.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13860
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13861 @node Syntax, count-words-in-defun, Words and Symbols, Words in a defun
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13862 @section What Constitutes a Word or Symbol?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13863 @cindex Syntax categories and tables
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13864
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13865 Emacs treats different characters as belonging to different
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13866 @dfn{syntax categories}. For example, the regular expression,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13867 @samp{\\w+}, is a pattern specifying one or more @emph{word
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13868 constituent} characters. Word constituent characters are members of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13869 one syntax category. Other syntax categories include the class of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13870 punctuation characters, such as the period and the comma, and the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13871 class of whitespace characters, such as the blank space and the tab
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13872 character. (For more information, see @ref{Syntax, Syntax, The Syntax
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13873 Table, emacs, The GNU Emacs Manual}, and @ref{Syntax Tables, , Syntax
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13874 Tables, elisp, The GNU Emacs Lisp Reference Manual}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13875
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13876 Syntax tables specify which characters belong to which categories.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13877 Usually, a hyphen is not specified as a `word constituent character'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13878 Instead, it is specified as being in the `class of characters that are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13879 part of symbol names but not words.' This means that the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13880 @code{count-words-region} function treats it in the same way it treats
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13881 an interword white space, which is why @code{count-words-region}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13882 counts @samp{multiply-by-seven} as three words.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13883
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13884 There are two ways to cause Emacs to count @samp{multiply-by-seven} as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13885 one symbol: modify the syntax table or modify the regular expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13886
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13887 We could redefine a hyphen as a word constituent character by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13888 modifying the syntax table that Emacs keeps for each mode. This
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13889 action would serve our purpose, except that a hyphen is merely the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13890 most common character within symbols that is not typically a word
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13891 constituent character; there are others, too.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13892
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13893 Alternatively, we can redefine the regular expression used in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13894 @code{count-words} definition so as to include symbols. This
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13895 procedure has the merit of clarity, but the task is a little tricky.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13896
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13897 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13898 The first part is simple enough: the pattern must match ``at least one
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13899 character that is a word or symbol constituent''. Thus:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13900
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13901 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13902 "\\(\\w\\|\\s_\\)+"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13903 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13904
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13905 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13906 The @samp{\\(} is the first part of the grouping construct that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13907 includes the @samp{\\w} and the @samp{\\s_} as alternatives, separated
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13908 by the @samp{\\|}. The @samp{\\w} matches any word-constituent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13909 character and the @samp{\\s_} matches any character that is part of a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13910 symbol name but not a word-constituent character. The @samp{+}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13911 following the group indicates that the word or symbol constituent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13912 characters must be matched at least once.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13913
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13914 However, the second part of the regexp is more difficult to design.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13915 What we want is to follow the first part with ``optionally one or more
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13916 characters that are not constituents of a word or symbol''. At first,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13917 I thought I could define this with the following:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13918
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13919 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13920 "\\(\\W\\|\\S_\\)*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13921 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13922
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13923 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13924 The upper case @samp{W} and @samp{S} match characters that are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13925 @emph{not} word or symbol constituents. Unfortunately, this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13926 expression matches any character that is either not a word constituent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13927 or not a symbol constituent. This matches any character!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13928
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13929 I then noticed that every word or symbol in my test region was
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13930 followed by white space (blank space, tab, or newline). So I tried
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13931 placing a pattern to match one or more blank spaces after the pattern
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13932 for one or more word or symbol constituents. This failed, too. Words
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13933 and symbols are often separated by whitespace, but in actual code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13934 parentheses may follow symbols and punctuation may follow words. So
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13935 finally, I designed a pattern in which the word or symbol constituents
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13936 are followed optionally by characters that are not white space and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13937 then followed optionally by white space.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13938
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13939 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13940 Here is the full regular expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13941
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13942 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13943 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13944 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13945
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13946 @node count-words-in-defun, Several defuns, Syntax, Words in a defun
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13947 @section The @code{count-words-in-defun} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13948 @cindex Counting words in a @code{defun}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13949
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13950 We have seen that there are several ways to write a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13951 @code{count-word-region} function. To write a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13952 @code{count-words-in-defun}, we need merely adapt one of these
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13953 versions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13954
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13955 The version that uses a @code{while} loop is easy to understand, so I
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13956 am going to adapt that. Because @code{count-words-in-defun} will be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13957 part of a more complex program, it need not be interactive and it need
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13958 not display a message but just return the count. These considerations
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13959 simplify the definition a little.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13960
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13961 On the other hand, @code{count-words-in-defun} will be used within a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13962 buffer that contains function definitions. Consequently, it is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13963 reasonable to ask that the function determine whether it is called
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13964 when point is within a function definition, and if it is, to return
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13965 the count for that definition. This adds complexity to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13966 definition, but saves us from needing to pass arguments to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13967 function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13968
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13969 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13970 These considerations lead us to prepare the following template:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13971
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13972 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13973 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13974 (defun count-words-in-defun ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13975 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13976 (@var{set up}@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13977 (@var{while loop}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13978 @var{return count})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13979 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13980 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13981
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13982 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13983 As usual, our job is to fill in the slots.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13984
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13985 First, the set up.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13986
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13987 We are presuming that this function will be called within a buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13988 containing function definitions. Point will either be within a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13989 function definition or not. For @code{count-words-in-defun} to work,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13990 point must move to the beginning of the definition, a counter must
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13991 start at zero, and the counting loop must stop when point reaches the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13992 end of the definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13993
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13994 The @code{beginning-of-defun} function searches backwards for an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13995 opening delimiter such as a @samp{(} at the beginning of a line, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13996 moves point to that position, or else to the limit of the search. In
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13997 practice, this means that @code{beginning-of-defun} moves point to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13998 beginning of an enclosing or preceding function definition, or else to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13999 the beginning of the buffer. We can use @code{beginning-of-defun} to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14000 place point where we wish to start.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14001
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14002 The @code{while} loop requires a counter to keep track of the words or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14003 symbols being counted. A @code{let} expression can be used to create
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14004 a local variable for this purpose, and bind it to an initial value of zero.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14005
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14006 The @code{end-of-defun} function works like @code{beginning-of-defun}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14007 except that it moves point to the end of the definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14008 @code{end-of-defun} can be used as part of an expression that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14009 determines the position of the end of the definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14010
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14011 The set up for @code{count-words-in-defun} takes shape rapidly: first
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14012 we move point to the beginning of the definition, then we create a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14013 local variable to hold the count, and finally, we record the position
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14014 of the end of the definition so the @code{while} loop will know when to stop
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14015 looping.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14016
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14017 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14018 The code looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14019
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14020 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14021 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14022 (beginning-of-defun)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14023 (let ((count 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14024 (end (save-excursion (end-of-defun) (point))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14025 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14026 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14027
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14028 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14029 The code is simple. The only slight complication is likely to concern
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14030 @code{end}: it is bound to the position of the end of the definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14031 by a @code{save-excursion} expression that returns the value of point
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14032 after @code{end-of-defun} temporarily moves it to the end of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14033 definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14034
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14035 The second part of the @code{count-words-in-defun}, after the set up,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14036 is the @code{while} loop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14037
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14038 The loop must contain an expression that jumps point forward word by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14039 word and symbol by symbol, and another expression that counts the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14040 jumps. The true-or-false-test for the @code{while} loop should test
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14041 true so long as point should jump forward, and false when point is at
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14042 the end of the definition. We have already redefined the regular
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14043 expression for this (@pxref{Syntax}), so the loop is straightforward:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14044
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14045 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14046 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14047 (while (and (< (point) end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14048 (re-search-forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14049 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" end t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14050 (setq count (1+ count)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14051 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14052 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14053
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14054 The third part of the function definition returns the count of words
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14055 and symbols. This part is the last expression within the body of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14056 @code{let} expression, and can be, very simply, the local variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14057 @code{count}, which when evaluated returns the count.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14058
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14059 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14060 Put together, the @code{count-words-in-defun} definition looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14061
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14062 @findex count-words-in-defun
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14063 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14064 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14065 (defun count-words-in-defun ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14066 "Return the number of words and symbols in a defun."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14067 (beginning-of-defun)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14068 (let ((count 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14069 (end (save-excursion (end-of-defun) (point))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14070 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14071 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14072 (while
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14073 (and (< (point) end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14074 (re-search-forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14075 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14076 end t))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14077 (setq count (1+ count)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14078 count))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14079 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14080 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14081
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14082 How to test this? The function is not interactive, but it is easy to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14083 put a wrapper around the function to make it interactive; we can use
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14084 almost the same code as for the recursive version of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14085 @code{count-words-region}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14086
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14087 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14088 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14089 ;;; @r{Interactive version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14090 (defun count-words-defun ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14091 "Number of words and symbols in a function definition."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14092 (interactive)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14093 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14094 "Counting words and symbols in function definition ... ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14095 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14096 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14097 (let ((count (count-words-in-defun)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14098 (cond
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14099 ((zerop count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14100 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14101 "The definition does NOT have any words or symbols."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14102 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14103 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14104 ((= 1 count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14105 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14106 "The definition has 1 word or symbol."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14107 (t
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14108 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14109 "The definition has %d words or symbols." count)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14110 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14111 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14112
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14113 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14114 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14115 Let's re-use @kbd{C-c =} as a convenient keybinding:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14116
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14117 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14118 (global-set-key "\C-c=" 'count-words-defun)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14119 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14120
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14121 Now we can try out @code{count-words-defun}: install both
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14122 @code{count-words-in-defun} and @code{count-words-defun}, and set the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14123 keybinding, and then place the cursor within the following definition:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14124
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14125 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14126 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14127 (defun multiply-by-seven (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14128 "Multiply NUMBER by seven."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14129 (* 7 number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14130 @result{} 10
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14131 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14132 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14133
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14134 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14135 Success! The definition has 10 words and symbols.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14136
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14137 The next problem is to count the numbers of words and symbols in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14138 several definitions within a single file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14139
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14140 @node Several defuns, Find a File, count-words-in-defun, Words in a defun
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14141 @section Count Several @code{defuns} Within a File
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14142
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14143 A file such as @file{simple.el} may have 80 or more function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14144 definitions within it. Our long term goal is to collect statistics on
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14145 many files, but as a first step, our immediate goal is to collect
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14146 statistics on one file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14147
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14148 The information will be a series of numbers, each number being the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14149 length of a function definition. We can store the numbers in a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14150
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14151 We know that we will want to incorporate the information regarding one
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14152 file with information about many other files; this means that the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14153 function for counting definition lengths within one file need only
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14154 return the list of lengths. It need not and should not display any
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14155 messages.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14156
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14157 The word count commands contain one expression to jump point forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14158 word by word and another expression to count the jumps. The function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14159 to return the lengths of definitions can be designed to work the same
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14160 way, with one expression to jump point forward definition by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14161 definition and another expression to construct the lengths' list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14162
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14163 This statement of the problem makes it elementary to write the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14164 function definition. Clearly, we will start the count at the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14165 beginning of the file, so the first command will be @code{(goto-char
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14166 (point-min))}. Next, we start the @code{while} loop; and the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14167 true-or-false test of the loop can be a regular expression search for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14168 the next function definition---so long as the search succeeds, point
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14169 is moved forward and then the body of the loop is evaluated. The body
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14170 needs an expression that constructs the lengths' list. @code{cons},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14171 the list construction command, can be used to create the list. That
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14172 is almost all there is to it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14173
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14174 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14175 Here is what this fragment of code looks like:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14176
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14177 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14178 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14179 (goto-char (point-min))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14180 (while (re-search-forward "^(defun" nil t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14181 (setq lengths-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14182 (cons (count-words-in-defun) lengths-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14183 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14184 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14185
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14186 What we have left out is the mechanism for finding the file that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14187 contains the function definitions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14188
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14189 In previous examples, we either used this, the Info file, or we
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14190 switched back and forth to some other buffer, such as the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14191 @file{*scratch*} buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14192
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14193 Finding a file is a new process that we have not yet discussed.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14194
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14195 @node Find a File, lengths-list-file, Several defuns, Words in a defun
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14196 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14197 @section Find a File
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14198 @cindex Find a File
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14199
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14200 To find a file in Emacs, you use the @kbd{C-x C-f} (@code{find-file})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14201 command. This command is almost, but not quite right for the lengths
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14202 problem.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14203
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14204 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14205 Let's look at the source for @code{find-file} (you can use the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14206 @code{find-tag} command or @kbd{C-h f} (@code{describe-function}) to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14207 find the source of a function):
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14208
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14209 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14210 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14211 (defun find-file (filename)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14212 "Edit file FILENAME.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14213 Switch to a buffer visiting file FILENAME,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14214 creating one if none already exists."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14215 (interactive "FFind file: ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14216 (switch-to-buffer (find-file-noselect filename)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14217 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14218 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14219
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14220 The definition possesses short but complete documentation and an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14221 interactive specification that prompts you for a file name when you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14222 use the command interactively. The body of the definition contains
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14223 two functions, @code{find-file-noselect} and @code{switch-to-buffer}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14224
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14225 According to its documentation as shown by @kbd{C-h f} (the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14226 @code{describe-function} command), the @code{find-file-noselect}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14227 function reads the named file into a buffer and returns the buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14228 However, the buffer is not selected. Emacs does not switch its
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14229 attention (or yours if you are using @code{find-file-noselect}) to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14230 named buffer. That is what @code{switch-to-buffer} does: it switches
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14231 the buffer to which Emacs attention is directed; and it switches the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14232 buffer displayed in the window to the new buffer. We have discussed
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14233 buffer switching elsewhere. (@xref{Switching Buffers}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14234
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14235 In this histogram project, we do not need to display each file on the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14236 screen as the program determines the length of each definition within
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14237 it. Instead of employing @code{switch-to-buffer}, we can work with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14238 @code{set-buffer}, which redirects the attention of the computer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14239 program to a different buffer but does not redisplay it on the screen.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14240 So instead of calling on @code{find-file} to do the job, we must write
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14241 our own expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14242
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14243 The task is easy: use @code{find-file-noselect} and @code{set-buffer}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14244
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14245 @node lengths-list-file, Several files, Find a File, Words in a defun
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14246 @section @code{lengths-list-file} in Detail
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14247
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14248 The core of the @code{lengths-list-file} function is a @code{while}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14249 loop containing a function to move point forward `defun by defun' and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14250 a function to count the number of words and symbols in each defun.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14251 This core must be surrounded by functions that do various other tasks,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14252 including finding the file, and ensuring that point starts out at the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14253 beginning of the file. The function definition looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14254 @findex lengths-list-file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14255
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14256 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14257 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14258 (defun lengths-list-file (filename)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14259 "Return list of definitions' lengths within FILE.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14260 The returned list is a list of numbers.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14261 Each number is the number of words or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14262 symbols in one function definition."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14263 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14264 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14265 (message "Working on `%s' ... " filename)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14266 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14267 (let ((buffer (find-file-noselect filename))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14268 (lengths-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14269 (set-buffer buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14270 (setq buffer-read-only t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14271 (widen)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14272 (goto-char (point-min))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14273 (while (re-search-forward "^(defun" nil t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14274 (setq lengths-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14275 (cons (count-words-in-defun) lengths-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14276 (kill-buffer buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14277 lengths-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14278 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14279 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14280
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14281 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14282 The function is passed one argument, the name of the file on which it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14283 will work. It has four lines of documentation, but no interactive
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14284 specification. Since people worry that a computer is broken if they
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14285 don't see anything going on, the first line of the body is a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14286 message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14287
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14288 The next line contains a @code{save-excursion} that returns Emacs'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14289 attention to the current buffer when the function completes. This is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14290 useful in case you embed this function in another function that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14291 presumes point is restored to the original buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14292
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14293 In the varlist of the @code{let} expression, Emacs finds the file and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14294 binds the local variable @code{buffer} to the buffer containing the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14295 file. At the same time, Emacs creates @code{lengths-list} as a local
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14296 variable.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14297
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14298 Next, Emacs switches its attention to the buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14299
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14300 In the following line, Emacs makes the buffer read-only. Ideally,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14301 this line is not necessary. None of the functions for counting words
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14302 and symbols in a function definition should change the buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14303 Besides, the buffer is not going to be saved, even if it were changed.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14304 This line is entirely the consequence of great, perhaps excessive,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14305 caution. The reason for the caution is that this function and those
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14306 it calls work on the sources for Emacs and it is very inconvenient if
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14307 they are inadvertently modified. It goes without saying that I did
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14308 not realize a need for this line until an experiment went awry and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14309 started to modify my Emacs source files @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14310
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14311 Next comes a call to widen the buffer if it is narrowed. This
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14312 function is usually not needed---Emacs creates a fresh buffer if none
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14313 already exists; but if a buffer visiting the file already exists Emacs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14314 returns that one. In this case, the buffer may be narrowed and must
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14315 be widened. If we wanted to be fully `user-friendly', we would
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14316 arrange to save the restriction and the location of point, but we
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14317 won't.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14318
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14319 The @code{(goto-char (point-min))} expression moves point to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14320 beginning of the buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14321
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14322 Then comes a @code{while} loop in which the `work' of the function is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14323 carried out. In the loop, Emacs determines the length of each
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14324 definition and constructs a lengths' list containing the information.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14325
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14326 Emacs kills the buffer after working through it. This is to save
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14327 space inside of Emacs. My version of Emacs 19 contained over 300
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14328 source files of interest; Emacs 21 contains over 800 source files.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14329 Another function will apply @code{lengths-list-file} to each of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14330 files.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14331
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14332 Finally, the last expression within the @code{let} expression is the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14333 @code{lengths-list} variable; its value is returned as the value of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14334 the whole function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14335
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14336 You can try this function by installing it in the usual fashion. Then
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14337 place your cursor after the following expression and type @kbd{C-x
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14338 C-e} (@code{eval-last-sexp}).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14339
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14340 @c !!! 21.0.100 lisp sources location here
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14341 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14342 (lengths-list-file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14343 "/usr/local/share/emacs/21.0.100/lisp/emacs-lisp/debug.el")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14344 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14345
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14346 @c was: (lengths-list-file "../lisp/debug.el")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14347 @c !!! as of 21, Info file is in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14348 @c /usr/share/info/emacs-lisp-intro.info.gz
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14349 @c but debug.el is in /usr/local/share/emacs/21.0.100/lisp/emacs-lisp/debug.el
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14350
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14351 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14352 (You may need to change the pathname of the file; the one here worked
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14353 with GNU Emacs version 21.0.100. To change the expression, copy it to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14354 the @file{*scratch*} buffer and edit it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14355
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14356 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14357 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14358 (Also, to see the full length of the list, rather than a truncated
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14359 version, you may have to evaluate the following:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14360
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14361 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14362 (custom-set-variables '(eval-expression-print-length nil))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14363 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14364
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14365 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14366 (@xref{defcustom, , Setting Variables with @code{defcustom}}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14367 Then evaluate the @code{lengths-list-file} expression.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14368
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14369 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14370 The lengths' list for @file{debug.el} takes less than a second to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14371 produce and looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14372
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14373 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14374 (77 95 85 87 131 89 50 25 44 44 68 35 64 45 17 34 167 457)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14375 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14376
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14377 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14378 (Using my old machine, the version 19 lengths' list for @file{debug.el}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14379 took seven seconds to produce and looked like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14380
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14381 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14382 (75 41 80 62 20 45 44 68 45 12 34 235)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14383 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14384
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14385 (The newer version of @file{debug.el} contains more defuns than the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14386 earlier one; and my new machine is much faster than the old one.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14387
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14388 Note that the length of the last definition in the file is first in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14389 the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14390
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14391 @node Several files, Several files recursively, lengths-list-file, Words in a defun
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14392 @section Count Words in @code{defuns} in Different Files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14393
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14394 In the previous section, we created a function that returns a list of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14395 the lengths of each definition in a file. Now, we want to define a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14396 function to return a master list of the lengths of the definitions in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14397 a list of files.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14398
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14399 Working on each of a list of files is a repetitious act, so we can use
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14400 either a @code{while} loop or recursion.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14401
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14402 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14403 * lengths-list-many-files:: Return a list of the lengths of defuns.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14404 * append:: Attach one list to another.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14405 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14406
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14407 @node lengths-list-many-files, append, Several files, Several files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14408 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14409 @unnumberedsubsec Determine the lengths of @code{defuns}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14410 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14411
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14412 The design using a @code{while} loop is routine. The argument passed
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14413 the function is a list of files. As we saw earlier (@pxref{Loop
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14414 Example}), you can write a @code{while} loop so that the body of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14415 loop is evaluated if such a list contains elements, but to exit the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14416 loop if the list is empty. For this design to work, the body of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14417 loop must contain an expression that shortens the list each time the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14418 body is evaluated, so that eventually the list is empty. The usual
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14419 technique is to set the value of the list to the value of the @sc{cdr}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14420 of the list each time the body is evaluated.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14422 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14423 The template looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14424
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14425 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14426 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14427 (while @var{test-whether-list-is-empty}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14428 @var{body}@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14429 @var{set-list-to-cdr-of-list})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14430 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14431 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14432
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14433 Also, we remember that a @code{while} loop returns @code{nil} (the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14434 result of evaluating the true-or-false-test), not the result of any
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14435 evaluation within its body. (The evaluations within the body of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14436 loop are done for their side effects.) However, the expression that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14437 sets the lengths' list is part of the body---and that is the value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14438 that we want returned by the function as a whole. To do this, we
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14439 enclose the @code{while} loop within a @code{let} expression, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14440 arrange that the last element of the @code{let} expression contains
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14441 the value of the lengths' list. (@xref{Incrementing Example, , Loop
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14442 Example with an Incrementing Counter}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14443
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14444 @findex lengths-list-many-files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14445 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14446 These considerations lead us directly to the function itself:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14447
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14448 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14449 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14450 ;;; @r{Use @code{while} loop.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14451 (defun lengths-list-many-files (list-of-files)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14452 "Return list of lengths of defuns in LIST-OF-FILES."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14453 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14454 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14455 (let (lengths-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14456
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14457 ;;; @r{true-or-false-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14458 (while list-of-files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14459 (setq lengths-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14460 (append
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14461 lengths-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14462
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14463 ;;; @r{Generate a lengths' list.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14464 (lengths-list-file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14465 (expand-file-name (car list-of-files)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14466 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14467
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14468 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14469 ;;; @r{Make files' list shorter.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14470 (setq list-of-files (cdr list-of-files)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14471
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14472 ;;; @r{Return final value of lengths' list.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14473 lengths-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14474 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14475 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14476
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14477 @code{expand-file-name} is a built-in function that converts a file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14478 name to the absolute, long, path name form of the directory in which
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14479 the function is called.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14480
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14481 @c !!! 21.0.100 lisp sources location here
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14482 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14483 Thus, if @code{expand-file-name} is called on @code{debug.el} when
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14484 Emacs is visiting the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14485 @file{/usr/local/share/emacs/21.0.100/lisp/emacs-lisp/} directory,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14486
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14487 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14488 debug.el
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14489 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14490
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14491 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14492 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14493 becomes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14494
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14495 @c !!! 21.0.100 lisp sources location here
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14496 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14497 /usr/local/share/emacs/21.0.100/lisp/emacs-lisp/debug.el
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14498 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14499
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14500 The only other new element of this function definition is the as yet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14501 unstudied function @code{append}, which merits a short section for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14502 itself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14503
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14504 @node append, , lengths-list-many-files, Several files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14505 @subsection The @code{append} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14506
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14507 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14508 The @code{append} function attaches one list to another. Thus,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14509
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14510 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14511 (append '(1 2 3 4) '(5 6 7 8))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14512 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14513
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14514 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14515 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14516 produces the list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14517
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14518 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14519 (1 2 3 4 5 6 7 8)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14520 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14521
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14522 This is exactly how we want to attach two lengths' lists produced by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14523 @code{lengths-list-file} to each other. The results contrast with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14524 @code{cons},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14525
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14526 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14527 (cons '(1 2 3 4) '(5 6 7 8))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14528 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14529
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14530 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14531 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14532 which constructs a new list in which the first argument to @code{cons}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14533 becomes the first element of the new list:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14534
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14535 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14536 ((1 2 3 4) 5 6 7 8)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14537 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14538
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14539 @node Several files recursively, Prepare the data, Several files, Words in a defun
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14540 @section Recursively Count Words in Different Files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14541
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14542 Besides a @code{while} loop, you can work on each of a list of files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14543 with recursion. A recursive version of @code{lengths-list-many-files}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14544 is short and simple.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14545
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14546 The recursive function has the usual parts: the `do-again-test', the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14547 `next-step-expression', and the recursive call. The `do-again-test'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14548 determines whether the function should call itself again, which it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14549 will do if the @code{list-of-files} contains any remaining elements;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14550 the `next-step-expression' resets the @code{list-of-files} to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14551 @sc{cdr} of itself, so eventually the list will be empty; and the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14552 recursive call calls itself on the shorter list. The complete
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14553 function is shorter than this description!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14554 @findex recursive-lengths-list-many-files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14555
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14556 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14557 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14558 (defun recursive-lengths-list-many-files (list-of-files)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14559 "Return list of lengths of each defun in LIST-OF-FILES."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14560 (if list-of-files ; @r{do-again-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14561 (append
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14562 (lengths-list-file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14563 (expand-file-name (car list-of-files)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14564 (recursive-lengths-list-many-files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14565 (cdr list-of-files)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14566 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14567 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14568
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14569 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14570 In a sentence, the function returns the lengths' list for the first of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14571 the @code{list-of-files} appended to the result of calling itself on
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14572 the rest of the @code{list-of-files}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14573
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14574 Here is a test of @code{recursive-lengths-list-many-files}, along with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14575 the results of running @code{lengths-list-file} on each of the files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14576 individually.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14577
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14578 Install @code{recursive-lengths-list-many-files} and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14579 @code{lengths-list-file}, if necessary, and then evaluate the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14580 following expressions. You may need to change the files' pathnames;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14581 those here work when this Info file and the Emacs sources are located
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14582 in their customary places. To change the expressions, copy them to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14583 the @file{*scratch*} buffer, edit them, and then evaluate them.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14584
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14585 The results are shown after the @samp{@result{}}. (These results are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14586 for files from Emacs Version 21.0.100; files from other versions of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14587 Emacs may produce different results.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14588
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14589 @c !!! 21.0.100 lisp sources location here
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14590 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14591 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14592 (cd "/usr/local/share/emacs/21.0.100/")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14593
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14594 (lengths-list-file "./lisp/macros.el")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14595 @result{} (273 263 456 90)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14596 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14597
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14598 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14599 (lengths-list-file "./lisp/mail/mailalias.el")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14600 @result{} (38 32 26 77 174 180 321 198 324)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14601 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14602
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14603 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14604 (lengths-list-file "./lisp/makesum.el")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14605 @result{} (85 181)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14606 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14607
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14608 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14609 (recursive-lengths-list-many-files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14610 '("./lisp/macros.el"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14611 "./lisp/mail/mailalias.el"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14612 "./lisp/makesum.el"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14613 @result{} (273 263 456 90 38 32 26 77 174 180 321 198 324 85 181)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14614 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14615 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14616
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14617 The @code{recursive-lengths-list-many-files} function produces the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14618 output we want.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14619
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14620 The next step is to prepare the data in the list for display in a graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14621
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14622 @node Prepare the data, , Several files recursively, Words in a defun
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14623 @section Prepare the Data for Display in a Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14624
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14625 The @code{recursive-lengths-list-many-files} function returns a list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14626 of numbers. Each number records the length of a function definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14627 What we need to do now is transform this data into a list of numbers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14628 suitable for generating a graph. The new list will tell how many
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14629 functions definitions contain less than 10 words and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14630 symbols, how many contain between 10 and 19 words and symbols, how
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14631 many contain between 20 and 29 words and symbols, and so on.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14632
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14633 In brief, we need to go through the lengths' list produced by the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14634 @code{recursive-lengths-list-many-files} function and count the number
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14635 of defuns within each range of lengths, and produce a list of those
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14636 numbers.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14637
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14638 Based on what we have done before, we can readily foresee that it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14639 should not be too hard to write a function that `@sc{cdr}s' down the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14640 lengths' list, looks at each element, determines which length range it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14641 is in, and increments a counter for that range.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14642
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14643 However, before beginning to write such a function, we should consider
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14644 the advantages of sorting the lengths' list first, so the numbers are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14645 ordered from smallest to largest. First, sorting will make it easier
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14646 to count the numbers in each range, since two adjacent numbers will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14647 either be in the same length range or in adjacent ranges. Second, by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14648 inspecting a sorted list, we can discover the highest and lowest
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14649 number, and thereby determine the largest and smallest length range
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14650 that we will need.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14651
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14652 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14653 * Sorting:: Sorting lists.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14654 * Files List:: Making a list of files.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14655 * Counting function definitions::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14656 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14657
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14658 @node Sorting, Files List, Prepare the data, Prepare the data
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14659 @subsection Sorting Lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14660 @findex sort
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14661
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14662 Emacs contains a function to sort lists, called (as you might guess)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14663 @code{sort}. The @code{sort} function takes two arguments, the list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14664 to be sorted, and a predicate that determines whether the first of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14665 two list elements is ``less'' than the second.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14666
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14667 As we saw earlier (@pxref{Wrong Type of Argument, , Using the Wrong
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14668 Type Object as an Argument}), a predicate is a function that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14669 determines whether some property is true or false. The @code{sort}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14670 function will reorder a list according to whatever property the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14671 predicate uses; this means that @code{sort} can be used to sort
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14672 non-numeric lists by non-numeric criteria---it can, for example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14673 alphabetize a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14674
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14675 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14676 The @code{<} function is used when sorting a numeric list. For example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14677
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14678 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14679 (sort '(4 8 21 17 33 7 21 7) '<)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14680 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14681
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14682 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14683 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14684 produces this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14685
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14686 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14687 (4 7 7 8 17 21 21 33)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14688 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14689
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14690 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14691 (Note that in this example, both the arguments are quoted so that the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14692 symbols are not evaluated before being passed to @code{sort} as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14693 arguments.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14694
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14695 Sorting the list returned by the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14696 @code{recursive-lengths-list-many-files} function is straightforward;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14697 it uses the @code{<} function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14698
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14699 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14700 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14701 (sort
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14702 (recursive-lengths-list-many-files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14703 '("../lisp/macros.el"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14704 "../lisp/mailalias.el"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14705 "../lisp/makesum.el"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14706 '<
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14707 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14708 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14709
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14710 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14711 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14712 which produces:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14713
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14714 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14715 (85 86 116 122 154 176 179 265)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14716 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14717
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14718 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14719 (Note that in this example, the first argument to @code{sort} is not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14720 quoted, since the expression must be evaluated so as to produce the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14721 list that is passed to @code{sort}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14722
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14723 @node Files List, Counting function definitions, Sorting, Prepare the data
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14724 @subsection Making a List of Files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14725
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14726 The @code{recursive-lengths-list-many-files} function requires a list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14727 of files as its argument. For our test examples, we constructed such
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14728 a list by hand; but the Emacs Lisp source directory is too large for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14729 us to do for that. Instead, we will write a function to do the job
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14730 for us. In this function, we will use both a @code{while} loop and a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14731 recursive call.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14732
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14733 @findex directory-files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14734 We did not have to write a function like this for older versions of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14735 GNU Emacs, since they placed all the @samp{.el} files in one
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14736 directory. Instead, we were able to use the @code{directory-files}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14737 function, which lists the names of files that match a specified
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14738 pattern within a single directory.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14739
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14740 However, recent versions of Emacs place Emacs Lisp files in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14741 sub-directories of the top level @file{lisp} directory. This
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14742 re-arrangement eases navigation. For example, all the mail related
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14743 files are in a @file{lisp} sub-directory called @file{mail}. But at
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14744 the same time, this arrangement forces us to create a file listing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14745 function that descends into the sub-directories.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14746
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14747 @findex files-in-below-directory
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14748 We can create this function, called @code{files-in-below-directory},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14749 using familiar functions such as @code{car}, @code{nthcdr}, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14750 @code{substring} in conjunction with an existing function called
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14751 @code{directory-files-and-attributes}. This latter function not only
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14752 lists all the filenames in a directory, including the names
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14753 of sub-directories, but also their attributes.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14754
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14755 To restate our goal: to create a function that will enable us
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14756 to feed filenames to @code{recursive-lengths-list-many-files}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14757 as a list that looks like this (but with more elements):
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14758
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14759 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14760 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14761 ("../lisp/macros.el"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14762 "../lisp/mail/rmail.el"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14763 "../lisp/makesum.el")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14764 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14765 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14766
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14767 The @code{directory-files-and-attributes} function returns a list of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14768 lists. Each of the lists within the main list consists of 13
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14769 elements. The first element is a string that contains the name of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14770 file -- which, in GNU/Linux, may be a `directory file', that is to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14771 say, a file with the special attributes of a directory. The second
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14772 element of the list is @code{t} for a directory, a string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14773 for symbolic link (the string is the name linked to), or @code{nil}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14774
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14775 For example, the first @samp{.el} file in the @file{lisp/} directory
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14776 is @file{abbrev.el}. Its name is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14777 @file{/usr/local/share/emacs/21.0.100/lisp/abbrev.el} and it is not a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14778 directory or a symbolic link.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14779
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14780 @need 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14781 This is how @code{directory-files-and-attributes} lists that file and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14782 its attributes:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14783
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14784 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14785 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14786 ("/usr/local/share/emacs/21.0.100/lisp/abbrev.el"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14787 nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14788 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14789 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14790 100
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14791 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14792 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14793 (15019 32380)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14794 (14883 48041)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14795 (15214 49336)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14796 11583
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14797 "-rw-rw-r--"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14798 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14799 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14800 t
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14801 341385
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14802 776)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14803 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14804 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14805
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14806 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14807 On the other hand, @file{mail/} is a directory within the @file{lisp/}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14808 directory. The beginning of its listing looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14809
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14810 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14811 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14812 ("/usr/local/share/emacs/21.0.100/lisp/mail"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14813 t
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14814 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14815 )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14816 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14817 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14818
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14819 (Look at the documentation of @code{file-attributes} to learn about
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14820 the different attributes. Bear in mind that the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14821 @code{file-attributes} function does not list the filename, so its
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14822 first element is @code{directory-files-and-attributes}'s second
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14823 element.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14824
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14825 We will want our new function, @code{files-in-below-directory}, to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14826 list the @samp{.el} files in the directory it is told to check, and in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14827 any directories below that directory.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14828
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14829 This gives us a hint on how to construct
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14830 @code{files-in-below-directory}: within a directory, the function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14831 should add @samp{.el} filenames to a list; and if, within a directory,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14832 the function comes upon a sub-directory, it should go into that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14833 sub-directory and repeat its actions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14834
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14835 However, we should note that every directory contains a name that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14836 refers to itself, called @file{.}, (``dot'') and a name that refers to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14837 its parent directory, called @file{..} (``double dot''). (In
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14838 @file{/}, the root directory, @file{..} refers to itself, since
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14839 @file{/} has no parent.) Clearly, we do not want our
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14840 @code{files-in-below-directory} function to enter those directories,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14841 since they always lead us, directly or indirectly, to the current
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14842 directory.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14843
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14844 Consequently, our @code{files-in-below-directory} function must do
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14845 several tasks:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14846
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14847 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14848 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14849 Check to see whether it is looking at a filename that ends in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14850 @samp{.el}; and if so, add its name to a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14851
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14852 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14853 Check to see whether it is looking at a filename that is the name of a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14854 directory; and if so,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14855
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14856 @itemize @minus
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14857 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14858 Check to see whether it is looking at @file{.} or @file{..}; and if
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14859 so skip it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14860
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14861 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14862 Or else, go into that directory and repeat the process.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14863 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14864 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14865
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14866 Let's write a function definition to do these tasks. We will use a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14867 @code{while} loop to move from one filename to another within a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14868 directory, checking what needs to be done; and we will use a recursive
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14869 call to repeat the actions on each sub-directory. The recursive
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14870 pattern is `accumulate'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14871 (@pxref{Accumulate, , Recursive Pattern: @emph{accumulate}}),
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14872 using @code{append} as the combiner.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14873
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14874 @ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14875 (directory-files "/usr/local/share/emacs/21.0.100/lisp/" t "\\.el$")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14876 (shell-command "find /usr/local/share/emacs/21.0.100/lisp/ -name '*.el'")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14877 @end ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14878
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14879 @c /usr/local/share/emacs/21.0.100/lisp/
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14880
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14881 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14882 Here is the function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14883
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14884 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14885 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14886 (defun files-in-below-directory (directory)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14887 "List the .el files in DIRECTORY and in its sub-directories."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14888 ;; Although the function will be used non-interactively,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14889 ;; it will be easier to test if we make it interactive.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14890 ;; The directory will have a name such as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14891 ;; "/usr/local/share/emacs/21.0.100/lisp/"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14892 (interactive "DDirectory name: ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14893 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14894 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14895 (let (el-files-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14896 (current-directory-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14897 (directory-files-and-attributes directory t)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14898 ;; while we are in the current directory
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14899 (while current-directory-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14900 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14901 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14902 (cond
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14903 ;; check to see whether filename ends in `.el'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14904 ;; and if so, append its name to a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14905 ((equal ".el" (substring (car (car current-directory-list)) -3))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14906 (setq el-files-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14907 (cons (car (car current-directory-list)) el-files-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14908 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14909 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14910 ;; check whether filename is that of a directory
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14911 ((eq t (car (cdr (car current-directory-list))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14912 ;; decide whether to skip or recurse
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14913 (if
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14914 (equal (or "." "..")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14915 (substring (car (car current-directory-list)) -1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14916 ;; then do nothing if filename is that of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14917 ;; current directory or parent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14918 ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14919 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14920 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14921 ;; else descend into the directory and repeat the process
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14922 (setq el-files-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14923 (append
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14924 (files-in-below-directory
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14925 (car (car current-directory-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14926 el-files-list)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14927 ;; move to the next filename in the list; this also
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14928 ;; shortens the list so the while loop eventually comes to an end
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14929 (setq current-directory-list (cdr current-directory-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14930 ;; return the filenames
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14931 el-files-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14932 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14933 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14934
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14935 @c (files-in-below-directory "/usr/local/share/emacs/21.0.100/lisp/")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14936
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14937 The @code{files-in-below-directory} @code{directory-files} function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14938 takes one argument, the name of a directory.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14939
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14940 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14941 Thus, on my system,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14942
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14943 @c !!! 21.0.100 lisp sources location here
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14944 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14945 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14946 (length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14947 (files-in-below-directory "/usr/local/share/emacs/21.0.100/lisp/"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14948 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14949 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14950
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14951 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14952 tells me that my version 21.0.100 Lisp sources directory contains 754
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14953 @samp{.el} files.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14954
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14955 @code{files-in-below-directory} returns a list in reverse alphabetical
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14956 order. An expression to sort the list in alphabetical order looks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14957 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14958
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14959 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14960 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14961 (sort
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14962 (files-in-below-directory "/usr/local/share/emacs/21.0.100/lisp/")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14963 'string-lessp)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14964 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14965 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14966
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14967 @ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14968 (defun test ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14969 "Test how long it takes to find lengths of all elisp defuns."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14970 (insert "\n" (current-time-string) "\n")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14971 (sit-for 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14972 (sort
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14973 (recursive-lengths-list-many-files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14974 '("../lisp/macros.el"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14975 "../lisp/mailalias.el"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14976 "../lisp/makesum.el"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14977 '<)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14978 (insert (format "%s" (current-time-string))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14979
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14980 @end ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14981
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14982 @node Counting function definitions, , Files List, Prepare the data
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14983 @subsection Counting function definitions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14984
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14985 Our immediate goal is to generate a list that tells us how many
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14986 function definitions contain fewer than 10 words and symbols, how many
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14987 contain between 10 and 19 words and symbols, how many contain between
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14988 20 and 29 words and symbols, and so on.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14989
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14990 With a sorted list of numbers, this is easy: count how many elements
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14991 of the list are smaller than 10, then, after moving past the numbers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14992 just counted, count how many are smaller than 20, then, after moving
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14993 past the numbers just counted, count how many are smaller than 30, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14994 so on. Each of the numbers, 10, 20, 30, 40, and the like, is one
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14995 larger than the top of that range. We can call the list of such
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14996 numbers the @code{top-of-ranges} list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14997
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14998 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14999 If we wished, we could generate this list automatically, but it is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15000 simpler to write a list manually. Here it is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15001 @vindex top-of-ranges
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15002
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15003 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15004 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15005 (defvar top-of-ranges
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15006 '(10 20 30 40 50
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15007 60 70 80 90 100
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15008 110 120 130 140 150
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15009 160 170 180 190 200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15010 210 220 230 240 250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15011 260 270 280 290 300)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15012 "List specifying ranges for `defuns-per-range'.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15013 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15014 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15015
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15016 To change the ranges, we edit this list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15017
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15018 Next, we need to write the function that creates the list of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15019 number of definitions within each range. Clearly, this function must
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15020 take the @code{sorted-lengths} and the @code{top-of-ranges} lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15021 as arguments.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15022
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15023 The @code{defuns-per-range} function must do two things again and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15024 again: it must count the number of definitions within a range
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15025 specified by the current top-of-range value; and it must shift to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15026 next higher value in the @code{top-of-ranges} list after counting the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15027 number of definitions in the current range. Since each of these
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15028 actions is repetitive, we can use @code{while} loops for the job.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15029 One loop counts the number of definitions in the range defined by the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15030 current top-of-range value, and the other loop selects each of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15031 top-of-range values in turn.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15032
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15033 Several entries of the @code{sorted-lengths} list are counted for each
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15034 range; this means that the loop for the @code{sorted-lengths} list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15035 will be inside the loop for the @code{top-of-ranges} list, like a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15036 small gear inside a big gear.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15037
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15038 The inner loop counts the number of definitions within the range. It
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15039 is a simple counting loop of the type we have seen before.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15040 (@xref{Incrementing Loop, , A loop with an incrementing counter}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15041 The true-or-false test of the loop tests whether the value from the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15042 @code{sorted-lengths} list is smaller than the current value of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15043 top of the range. If it is, the function increments the counter and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15044 tests the next value from the @code{sorted-lengths} list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15045
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15046 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15047 The inner loop looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15048
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15049 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15050 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15051 (while @var{length-element-smaller-than-top-of-range}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15052 (setq number-within-range (1+ number-within-range))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15053 (setq sorted-lengths (cdr sorted-lengths)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15054 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15055 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15056
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15057 The outer loop must start with the lowest value of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15058 @code{top-of-ranges} list, and then be set to each of the succeeding
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15059 higher values in turn. This can be done with a loop like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15060
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15061 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15062 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15063 (while top-of-ranges
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15064 @var{body-of-loop}@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15065 (setq top-of-ranges (cdr top-of-ranges)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15066 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15067 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15068
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15069 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15070 Put together, the two loops look like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15071
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15072 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15073 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15074 (while top-of-ranges
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15075
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15076 ;; @r{Count the number of elements within the current range.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15077 (while @var{length-element-smaller-than-top-of-range}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15078 (setq number-within-range (1+ number-within-range))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15079 (setq sorted-lengths (cdr sorted-lengths)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15080
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15081 ;; @r{Move to next range.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15082 (setq top-of-ranges (cdr top-of-ranges)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15083 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15084 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15085
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15086 In addition, in each circuit of the outer loop, Emacs should record
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15087 the number of definitions within that range (the value of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15088 @code{number-within-range}) in a list. We can use @code{cons} for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15089 this purpose. (@xref{cons, , @code{cons}}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15090
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15091 The @code{cons} function works fine, except that the list it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15092 constructs will contain the number of definitions for the highest
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15093 range at its beginning and the number of definitions for the lowest
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15094 range at its end. This is because @code{cons} attaches new elements
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15095 of the list to the beginning of the list, and since the two loops are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15096 working their way through the lengths' list from the lower end first,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15097 the @code{defuns-per-range-list} will end up largest number first.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15098 But we will want to print our graph with smallest values first and the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15099 larger later. The solution is to reverse the order of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15100 @code{defuns-per-range-list}. We can do this using the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15101 @code{nreverse} function, which reverses the order of a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15102 @findex nreverse
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15103
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15104 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15105 For example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15106
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15107 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15108 (nreverse '(1 2 3 4))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15109 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15110
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15111 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15112 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15113 produces:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15114
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15115 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15116 (4 3 2 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15117 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15118
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15119 Note that the @code{nreverse} function is ``destructive''---that is,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15120 it changes the list to which it is applied; this contrasts with the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15121 @code{car} and @code{cdr} functions, which are non-destructive. In
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15122 this case, we do not want the original @code{defuns-per-range-list},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15123 so it does not matter that it is destroyed. (The @code{reverse}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15124 function provides a reversed copy of a list, leaving the original list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15125 as is.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15126 @findex reverse
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15127
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15128 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15129 Put all together, the @code{defuns-per-range} looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15130
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15131 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15132 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15133 (defun defuns-per-range (sorted-lengths top-of-ranges)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15134 "SORTED-LENGTHS defuns in each TOP-OF-RANGES range."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15135 (let ((top-of-range (car top-of-ranges))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15136 (number-within-range 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15137 defuns-per-range-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15138 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15139
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15140 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15141 ;; @r{Outer loop.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15142 (while top-of-ranges
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15143 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15144
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15145 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15146 ;; @r{Inner loop.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15147 (while (and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15148 ;; @r{Need number for numeric test.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15149 (car sorted-lengths)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15150 (< (car sorted-lengths) top-of-range))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15151 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15152
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15153 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15154 ;; @r{Count number of definitions within current range.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15155 (setq number-within-range (1+ number-within-range))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15156 (setq sorted-lengths (cdr sorted-lengths)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15157
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15158 ;; @r{Exit inner loop but remain within outer loop.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15159 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15160
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15161 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15162 (setq defuns-per-range-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15163 (cons number-within-range defuns-per-range-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15164 (setq number-within-range 0) ; @r{Reset count to zero.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15165 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15166
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15167 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15168 ;; @r{Move to next range.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15169 (setq top-of-ranges (cdr top-of-ranges))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15170 ;; @r{Specify next top of range value.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15171 (setq top-of-range (car top-of-ranges)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15172 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15173
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15174 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15175 ;; @r{Exit outer loop and count the number of defuns larger than}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15176 ;; @r{ the largest top-of-range value.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15177 (setq defuns-per-range-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15178 (cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15179 (length sorted-lengths)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15180 defuns-per-range-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15181 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15182
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15183 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15184 ;; @r{Return a list of the number of definitions within each range,}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15185 ;; @r{ smallest to largest.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15186 (nreverse defuns-per-range-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15187 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15188 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15189
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15190 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15191 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15192 The function is straightforward except for one subtle feature. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15193 true-or-false test of the inner loop looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15194
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15195 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15196 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15197 (and (car sorted-lengths)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15198 (< (car sorted-lengths) top-of-range))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15199 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15200 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15201
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15202 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15203 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15204 instead of like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15205
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15206 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15207 (< (car sorted-lengths) top-of-range)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15208 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15209
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15210 The purpose of the test is to determine whether the first item in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15211 @code{sorted-lengths} list is less than the value of the top of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15212 range.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15213
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15214 The simple version of the test works fine unless the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15215 @code{sorted-lengths} list has a @code{nil} value. In that case, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15216 @code{(car sorted-lengths)} expression function returns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15217 @code{nil}. The @code{<} function cannot compare a number to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15218 @code{nil}, which is an empty list, so Emacs signals an error and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15219 stops the function from attempting to continue to execute.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15220
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15221 The @code{sorted-lengths} list always becomes @code{nil} when the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15222 counter reaches the end of the list. This means that any attempt to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15223 use the @code{defuns-per-range} function with the simple version of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15224 the test will fail.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15225
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15226 We solve the problem by using the @code{(car sorted-lengths)}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15227 expression in conjunction with the @code{and} expression. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15228 @code{(car sorted-lengths)} expression returns a non-@code{nil}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15229 value so long as the list has at least one number within it, but
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15230 returns @code{nil} if the list is empty. The @code{and} expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15231 first evaluates the @code{(car sorted-lengths)} expression, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15232 if it is @code{nil}, returns false @emph{without} evaluating the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15233 @code{<} expression. But if the @code{(car sorted-lengths)}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15234 expression returns a non-@code{nil} value, the @code{and} expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15235 evaluates the @code{<} expression, and returns that value as the value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15236 of the @code{and} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15237
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15238 @c colon in printed section title causes problem in Info cross reference
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15239 This way, we avoid an error.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15240 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15241 @xref{forward-paragraph, , @code{forward-paragraph}: a Goldmine of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15242 Functions}, for more information about @code{and}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15243 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15244 @ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15245 @xref{forward-paragraph}, for more information about @code{and}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15246 @end ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15247
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15248 Here is a short test of the @code{defuns-per-range} function. First,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15249 evaluate the expression that binds (a shortened)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15250 @code{top-of-ranges} list to the list of values, then evaluate the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15251 expression for binding the @code{sorted-lengths} list, and then
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15252 evaluate the @code{defuns-per-range} function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15253
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15254 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15255 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15256 ;; @r{(Shorter list than we will use later.)}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15257 (setq top-of-ranges
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15258 '(110 120 130 140 150
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15259 160 170 180 190 200))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15260
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15261 (setq sorted-lengths
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15262 '(85 86 110 116 122 129 154 176 179 200 265 300 300))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15263
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15264 (defuns-per-range sorted-lengths top-of-ranges)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15265 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15266 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15267
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15268 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15269 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15270 The list returned looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15271
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15272 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15273 (2 2 2 0 0 1 0 2 0 0 4)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15274 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15275
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15276 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15277 Indeed, there are two elements of the @code{sorted-lengths} list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15278 smaller than 110, two elements between 110 and 119, two elements
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15279 between 120 and 129, and so on. There are four elements with a value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15280 of 200 or larger.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15281
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15282 @c The next step is to turn this numbers' list into a graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15283
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15284 @node Readying a Graph, Emacs Initialization, Words in a defun, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15285 @chapter Readying a Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15286 @cindex Readying a graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15287 @cindex Graph prototype
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15288 @cindex Prototype graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15289 @cindex Body of graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15290
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15291 Our goal is to construct a graph showing the numbers of function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15292 definitions of various lengths in the Emacs lisp sources.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15293
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15294 As a practical matter, if you were creating a graph, you would
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15295 probably use a program such as @code{gnuplot} to do the job.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15296 (@code{gnuplot} is nicely integrated into GNU Emacs.) In this case,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15297 however, we create one from scratch, and in the process we will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15298 re-acquaint ourselves with some of what we learned before and learn
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15299 more.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15300
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15301 In this chapter, we will first write a simple graph printing function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15302 This first definition will be a @dfn{prototype}, a rapidly written
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15303 function that enables us to reconnoiter this unknown graph-making
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15304 territory. We will discover dragons, or find that they are myth.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15305 After scouting the terrain, we will feel more confident and enhance
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15306 the function to label the axes automatically.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15307
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15308 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15309 * Columns of a graph::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15310 * graph-body-print:: How to print the body of a graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15311 * recursive-graph-body-print::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15312 * Printed Axes::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15313 * Line Graph Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15314 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15315
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15316 @node Columns of a graph, graph-body-print, Readying a Graph, Readying a Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15317 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15318 @unnumberedsec Printing the Columns of a Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15319 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15320
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15321 Since Emacs is designed to be flexible and work with all kinds of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15322 terminals, including character-only terminals, the graph will need to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15323 be made from one of the `typewriter' symbols. An asterisk will do; as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15324 we enhance the graph-printing function, we can make the choice of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15325 symbol a user option.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15326
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15327 We can call this function @code{graph-body-print}; it will take a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15328 @code{numbers-list} as its only argument. At this stage, we will not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15329 label the graph, but only print its body.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15330
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15331 The @code{graph-body-print} function inserts a vertical column of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15332 asterisks for each element in the @code{numbers-list}. The height of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15333 each line is determined by the value of that element of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15334 @code{numbers-list}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15335
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15336 Inserting columns is a repetitive act; that means that this function can
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15337 be written either with a @code{while} loop or recursively.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15338
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15339 Our first challenge is to discover how to print a column of asterisks.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15340 Usually, in Emacs, we print characters onto a screen horizontally,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15341 line by line, by typing. We have two routes we can follow: write our
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15342 own column-insertion function or discover whether one exists in Emacs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15343
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15344 To see whether there is one in Emacs, we can use the @kbd{M-x apropos}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15345 command. This command is like the @kbd{C-h a} (command-apropos)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15346 command, except that the latter finds only those functions that are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15347 commands. The @kbd{M-x apropos} command lists all symbols that match
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15348 a regular expression, including functions that are not interactive.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15349 @findex apropos
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15350
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15351 What we want to look for is some command that prints or inserts
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15352 columns. Very likely, the name of the function will contain either
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15353 the word `print' or the word `insert' or the word `column'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15354 Therefore, we can simply type @kbd{M-x apropos RET
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15355 print\|insert\|column RET} and look at the result. On my system, this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15356 command takes quite some time, and then produces a list of 79
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15357 functions and variables. Scanning down the list, the only function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15358 that looks as if it might do the job is @code{insert-rectangle}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15359
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15360 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15361 Indeed, this is the function we want; its documentation says:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15362
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15363 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15364 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15365 insert-rectangle:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15366 Insert text of RECTANGLE with upper left corner at point.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15367 RECTANGLE's first line is inserted at point,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15368 its second line is inserted at a point vertically under point, etc.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15369 RECTANGLE should be a list of strings.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15370 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15371 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15372
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15373 We can run a quick test, to make sure it does what we expect of it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15374
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15375 Here is the result of placing the cursor after the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15376 @code{insert-rectangle} expression and typing @kbd{C-u C-x C-e}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15377 (@code{eval-last-sexp}). The function inserts the strings
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15378 @samp{"first"}, @samp{"second"}, and @samp{"third"} at and below
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15379 point. Also the function returns @code{nil}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15380
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15381 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15382 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15383 (insert-rectangle '("first" "second" "third"))first
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15384 second
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15385 third
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15386 nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15387 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15388 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15389
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15390 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15391 Of course, we won't be inserting the text of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15392 @code{insert-rectangle} expression itself into the buffer in which we
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15393 are making the graph, but will call the function from our program. We
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15394 shall, however, have to make sure that point is in the buffer at the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15395 place where the @code{insert-rectangle} function will insert its
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15396 column of strings.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15397
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15398 If you are reading this in Info, you can see how this works by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15399 switching to another buffer, such as the @file{*scratch*} buffer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15400 placing point somewhere in the buffer, typing @kbd{M-:},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15401 typing the @code{insert-rectangle} expression into the minibuffer at
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15402 the prompt, and then typing @key{RET}. This causes Emacs to evaluate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15403 the expression in the minibuffer, but to use as the value of point the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15404 position of point in the @file{*scratch*} buffer. (@kbd{M-:}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15405 is the keybinding for @code{eval-expression}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15406
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15407 We find when we do this that point ends up at the end of the last
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15408 inserted line---that is to say, this function moves point as a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15409 side-effect. If we were to repeat the command, with point at this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15410 position, the next insertion would be below and to the right of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15411 previous insertion. We don't want this! If we are going to make a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15412 bar graph, the columns need to be beside each other.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15413
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15414 So we discover that each cycle of the column-inserting @code{while}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15415 loop must reposition point to the place we want it, and that place
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15416 will be at the top, not the bottom, of the column. Moreover, we
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15417 remember that when we print a graph, we do not expect all the columns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15418 to be the same height. This means that the top of each column may be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15419 at a different height from the previous one. We cannot simply
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15420 reposition point to the same line each time, but moved over to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15421 right---or perhaps we can@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15422
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15423 We are planning to make the columns of the bar graph out of asterisks.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15424 The number of asterisks in the column is the number specified by the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15425 current element of the @code{numbers-list}. We need to construct a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15426 list of asterisks of the right length for each call to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15427 @code{insert-rectangle}. If this list consists solely of the requisite
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15428 number of asterisks, then we will have position point the right number
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15429 of lines above the base for the graph to print correctly. This could
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15430 be difficult.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15431
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15432 Alternatively, if we can figure out some way to pass
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15433 @code{insert-rectangle} a list of the same length each time, then we
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15434 can place point on the same line each time, but move it over one
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15435 column to the right for each new column. If we do this, however, some
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15436 of the entries in the list passed to @code{insert-rectangle} must be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15437 blanks rather than asterisks. For example, if the maximum height of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15438 the graph is 5, but the height of the column is 3, then
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15439 @code{insert-rectangle} requires an argument that looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15440
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15441 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15442 (" " " " "*" "*" "*")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15443 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15444
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15445 This last proposal is not so difficult, so long as we can determine
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15446 the column height. There are two ways for us to specify the column
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15447 height: we can arbitrarily state what it will be, which would work
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15448 fine for graphs of that height; or we can search through the list of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15449 numbers and use the maximum height of the list as the maximum height
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15450 of the graph. If the latter operation were difficult, then the former
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15451 procedure would be easiest, but there is a function built into Emacs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15452 that determines the maximum of its arguments. We can use that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15453 function. The function is called @code{max} and it returns the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15454 largest of all its arguments, which must be numbers. Thus, for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15455 example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15456
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15457 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15458 (max 3 4 6 5 7 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15459 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15460
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15461 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15462 returns 7. (A corresponding function called @code{min} returns the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15463 smallest of all its arguments.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15464 @findex max
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15465 @findex min
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15466
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15467 However, we cannot simply call @code{max} on the @code{numbers-list};
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15468 the @code{max} function expects numbers as its argument, not a list of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15469 numbers. Thus, the following expression,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15470
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15471 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15472 (max '(3 4 6 5 7 3))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15473 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15474
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15475 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15476 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15477 produces the following error message;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15478
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15479 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15480 Wrong type of argument: number-or-marker-p, (3 4 6 5 7 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15481 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15482
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15483 @findex apply
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15484 We need a function that passes a list of arguments to a function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15485 This function is @code{apply}. This function `applies' its first
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15486 argument (a function) to its remaining arguments, the last of which
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15487 may be a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15488
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15489 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15490 For example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15491
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15492 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15493 (apply 'max 3 4 7 3 '(4 8 5))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15494 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15495
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15496 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15497 returns 8.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15498
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15499 (Incidentally, I don't know how you would learn of this function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15500 without a book such as this. It is possible to discover other
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15501 functions, like @code{search-forward} or @code{insert-rectangle}, by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15502 guessing at a part of their names and then using @code{apropos}. Even
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15503 though its base in metaphor is clear---`apply' its first argument to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15504 the rest---I doubt a novice would come up with that particular word
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15505 when using @code{apropos} or other aid. Of course, I could be wrong;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15506 after all, the function was first named by someone who had to invent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15507 it.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15508
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15509 The second and subsequent arguments to @code{apply} are optional, so
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15510 we can use @code{apply} to call a function and pass the elements of a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15511 list to it, like this, which also returns 8:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15512
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15513 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15514 (apply 'max '(4 8 5))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15515 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15516
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15517 This latter way is how we will use @code{apply}. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15518 @code{recursive-lengths-list-many-files} function returns a numbers'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15519 list to which we can apply @code{max} (we could also apply @code{max} to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15520 the sorted numbers' list; it does not matter whether the list is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15521 sorted or not.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15522
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15523 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15524 Hence, the operation for finding the maximum height of the graph is this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15525
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15526 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15527 (setq max-graph-height (apply 'max numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15528 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15529
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15530 Now we can return to the question of how to create a list of strings
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15531 for a column of the graph. Told the maximum height of the graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15532 and the number of asterisks that should appear in the column, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15533 function should return a list of strings for the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15534 @code{insert-rectangle} command to insert.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15535
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15536 Each column is made up of asterisks or blanks. Since the function is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15537 passed the value of the height of the column and the number of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15538 asterisks in the column, the number of blanks can be found by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15539 subtracting the number of asterisks from the height of the column.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15540 Given the number of blanks and the number of asterisks, two
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15541 @code{while} loops can be used to construct the list:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15542
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15543 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15544 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15545 ;;; @r{First version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15546 (defun column-of-graph (max-graph-height actual-height)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15547 "Return list of strings that is one column of a graph."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15548 (let ((insert-list nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15549 (number-of-top-blanks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15550 (- max-graph-height actual-height)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15551 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15552
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15553 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15554 ;; @r{Fill in asterisks.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15555 (while (> actual-height 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15556 (setq insert-list (cons "*" insert-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15557 (setq actual-height (1- actual-height)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15558 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15559
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15560 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15561 ;; @r{Fill in blanks.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15562 (while (> number-of-top-blanks 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15563 (setq insert-list (cons " " insert-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15564 (setq number-of-top-blanks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15565 (1- number-of-top-blanks)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15566 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15567
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15568 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15569 ;; @r{Return whole list.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15570 insert-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15571 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15572 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15573
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15574 If you install this function and then evaluate the following
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15575 expression you will see that it returns the list as desired:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15576
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15577 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15578 (column-of-graph 5 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15579 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15580
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15581 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15582 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15583 returns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15584
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15585 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15586 (" " " " "*" "*" "*")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15587 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15588
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15589 As written, @code{column-of-graph} contains a major flaw: the symbols
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15590 used for the blank and for the marked entries in the column are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15591 `hard-coded' as a space and asterisk. This is fine for a prototype,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15592 but you, or another user, may wish to use other symbols. For example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15593 in testing the graph function, you many want to use a period in place
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15594 of the space, to make sure the point is being repositioned properly
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15595 each time the @code{insert-rectangle} function is called; or you might
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15596 want to substitute a @samp{+} sign or other symbol for the asterisk.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15597 You might even want to make a graph-column that is more than one
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15598 display column wide. The program should be more flexible. The way to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15599 do that is to replace the blank and the asterisk with two variables
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15600 that we can call @code{graph-blank} and @code{graph-symbol} and define
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15601 those variables separately.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15602
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15603 Also, the documentation is not well written. These considerations
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15604 lead us to the second version of the function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15605
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15606 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15607 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15608 (defvar graph-symbol "*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15609 "String used as symbol in graph, usually an asterisk.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15610 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15611
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15612 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15613 (defvar graph-blank " "
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15614 "String used as blank in graph, usually a blank space.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15615 graph-blank must be the same number of columns wide
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15616 as graph-symbol.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15617 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15618 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15619
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15620 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15621 (For an explanation of @code{defvar}, see
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15622 @ref{defvar, , Initializing a Variable with @code{defvar}}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15623
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15624 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15625 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15626 ;;; @r{Second version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15627 (defun column-of-graph (max-graph-height actual-height)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15628 "Return MAX-GRAPH-HEIGHT strings; ACTUAL-HEIGHT are graph-symbols.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15629
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15630 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15631 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15632 The graph-symbols are contiguous entries at the end
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15633 of the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15634 The list will be inserted as one column of a graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15635 The strings are either graph-blank or graph-symbol."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15636 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15637
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15638 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15639 (let ((insert-list nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15640 (number-of-top-blanks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15641 (- max-graph-height actual-height)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15642 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15643
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15644 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15645 ;; @r{Fill in @code{graph-symbols}.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15646 (while (> actual-height 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15647 (setq insert-list (cons graph-symbol insert-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15648 (setq actual-height (1- actual-height)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15649 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15650
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15651 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15652 ;; @r{Fill in @code{graph-blanks}.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15653 (while (> number-of-top-blanks 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15654 (setq insert-list (cons graph-blank insert-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15655 (setq number-of-top-blanks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15656 (1- number-of-top-blanks)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15657
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15658 ;; @r{Return whole list.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15659 insert-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15660 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15661 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15662
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15663 If we wished, we could rewrite @code{column-of-graph} a third time to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15664 provide optionally for a line graph as well as for a bar graph. This
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15665 would not be hard to do. One way to think of a line graph is that it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15666 is no more than a bar graph in which the part of each bar that is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15667 below the top is blank. To construct a column for a line graph, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15668 function first constructs a list of blanks that is one shorter than
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15669 the value, then it uses @code{cons} to attach a graph symbol to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15670 list; then it uses @code{cons} again to attach the `top blanks' to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15671 the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15672
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15673 It is easy to see how to write such a function, but since we don't
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15674 need it, we will not do it. But the job could be done, and if it were
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15675 done, it would be done with @code{column-of-graph}. Even more
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15676 important, it is worth noting that few changes would have to be made
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15677 anywhere else. The enhancement, if we ever wish to make it, is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15678 simple.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15679
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15680 Now, finally, we come to our first actual graph printing function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15681 This prints the body of a graph, not the labels for the vertical and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15682 horizontal axes, so we can call this @code{graph-body-print}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15683
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15684 @node graph-body-print, recursive-graph-body-print, Columns of a graph, Readying a Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15685 @section The @code{graph-body-print} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15686 @findex graph-body-print
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15687
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15688 After our preparation in the preceding section, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15689 @code{graph-body-print} function is straightforward. The function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15690 will print column after column of asterisks and blanks, using the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15691 elements of a numbers' list to specify the number of asterisks in each
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15692 column. This is a repetitive act, which means we can use a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15693 decrementing @code{while} loop or recursive function for the job. In
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15694 this section, we will write the definition using a @code{while} loop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15695
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15696 The @code{column-of-graph} function requires the height of the graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15697 as an argument, so we should determine and record that as a local variable.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15698
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15699 This leads us to the following template for the @code{while} loop
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15700 version of this function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15701
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15702 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15703 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15704 (defun graph-body-print (numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15705 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15706 (let ((height @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15707 @dots{}))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15708 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15709
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15710 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15711 (while numbers-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15712 @var{insert-columns-and-reposition-point}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15713 (setq numbers-list (cdr numbers-list)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15714 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15715 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15716
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15717 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15718 We need to fill in the slots of the template.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15719
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15720 Clearly, we can use the @code{(apply 'max numbers-list)} expression to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15721 determine the height of the graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15722
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15723 The @code{while} loop will cycle through the @code{numbers-list} one
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15724 element at a time. As it is shortened by the @code{(setq numbers-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15725 (cdr numbers-list))} expression, the @sc{car} of each instance of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15726 list is the value of the argument for @code{column-of-graph}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15727
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15728 At each cycle of the @code{while} loop, the @code{insert-rectangle}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15729 function inserts the list returned by @code{column-of-graph}. Since
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15730 the @code{insert-rectangle} function moves point to the lower right of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15731 the inserted rectangle, we need to save the location of point at the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15732 time the rectangle is inserted, move back to that position after the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15733 rectangle is inserted, and then move horizontally to the next place
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15734 from which @code{insert-rectangle} is called.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15735
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15736 If the inserted columns are one character wide, as they will be if
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15737 single blanks and asterisks are used, the repositioning command is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15738 simply @code{(forward-char 1)}; however, the width of a column may be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15739 greater than one. This means that the repositioning command should be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15740 written @code{(forward-char symbol-width)}. The @code{symbol-width}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15741 itself is the length of a @code{graph-blank} and can be found using
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15742 the expression @code{(length graph-blank)}. The best place to bind
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15743 the @code{symbol-width} variable to the value of the width of graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15744 column is in the varlist of the @code{let} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15745
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15746 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15747 These considerations lead to the following function definition:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15748
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15749 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15750 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15751 (defun graph-body-print (numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15752 "Print a bar graph of the NUMBERS-LIST.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15753 The numbers-list consists of the Y-axis values."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15754
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15755 (let ((height (apply 'max numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15756 (symbol-width (length graph-blank))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15757 from-position)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15758 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15759
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15760 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15761 (while numbers-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15762 (setq from-position (point))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15763 (insert-rectangle
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15764 (column-of-graph height (car numbers-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15765 (goto-char from-position)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15766 (forward-char symbol-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15767 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15768 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15769 ;; @r{Draw graph column by column.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15770 (sit-for 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15771 (setq numbers-list (cdr numbers-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15772 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15773 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15774 ;; @r{Place point for X axis labels.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15775 (forward-line height)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15776 (insert "\n")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15777 ))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15778 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15779 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15780
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15781 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15782 The one unexpected expression in this function is the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15783 @w{@code{(sit-for 0)}} expression in the @code{while} loop. This
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15784 expression makes the graph printing operation more interesting to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15785 watch than it would be otherwise. The expression causes Emacs to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15786 `sit' or do nothing for a zero length of time and then redraw the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15787 screen. Placed here, it causes Emacs to redraw the screen column by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15788 column. Without it, Emacs would not redraw the screen until the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15789 function exits.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15790
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15791 We can test @code{graph-body-print} with a short list of numbers.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15792
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15793 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15794 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15795 Install @code{graph-symbol}, @code{graph-blank},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15796 @code{column-of-graph}, which are in
41499
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
15797 @iftex
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
15798 @ref{Readying a Graph, , Readying a Graph},
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
15799 @end iftex
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
15800 @ifinfo
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
15801 @ref{Columns of a graph},
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
15802 @end ifinfo
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15803 and @code{graph-body-print}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15804
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15805 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15806 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15807 Copy the following expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15808
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15809 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15810 (graph-body-print '(1 2 3 4 6 4 3 5 7 6 5 2 3))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15811 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15812
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15813 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15814 Switch to the @file{*scratch*} buffer and place the cursor where you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15815 want the graph to start.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15816
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15817 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15818 Type @kbd{M-:} (@code{eval-expression}).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15819
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15820 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15821 Yank the @code{graph-body-print} expression into the minibuffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15822 with @kbd{C-y} (@code{yank)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15823
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15824 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15825 Press @key{RET} to evaluate the @code{graph-body-print} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15826 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15827
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15828 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15829 Emacs will print a graph like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15830
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15831 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15832 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15833 *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15834 * **
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15835 * ****
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15836 *** ****
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15837 ********* *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15838 ************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15839 *************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15840 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15841 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15842
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15843 @node recursive-graph-body-print, Printed Axes, graph-body-print, Readying a Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15844 @section The @code{recursive-graph-body-print} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15845 @findex recursive-graph-body-print
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15846
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15847 The @code{graph-body-print} function may also be written recursively.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15848 The recursive solution is divided into two parts: an outside `wrapper'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15849 that uses a @code{let} expression to determine the values of several
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15850 variables that need only be found once, such as the maximum height of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15851 the graph, and an inside function that is called recursively to print
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15852 the graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15853
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15854 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15855 The `wrapper' is uncomplicated:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15856
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15857 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15858 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15859 (defun recursive-graph-body-print (numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15860 "Print a bar graph of the NUMBERS-LIST.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15861 The numbers-list consists of the Y-axis values."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15862 (let ((height (apply 'max numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15863 (symbol-width (length graph-blank))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15864 from-position)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15865 (recursive-graph-body-print-internal
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15866 numbers-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15867 height
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15868 symbol-width)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15869 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15870 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15871
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15872 The recursive function is a little more difficult. It has four parts:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15873 the `do-again-test', the printing code, the recursive call, and the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15874 `next-step-expression'. The `do-again-test' is an @code{if}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15875 expression that determines whether the @code{numbers-list} contains
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15876 any remaining elements; if it does, the function prints one column of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15877 the graph using the printing code and calls itself again. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15878 function calls itself again according to the value produced by the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15879 `next-step-expression' which causes the call to act on a shorter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15880 version of the @code{numbers-list}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15881
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15882 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15883 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15884 (defun recursive-graph-body-print-internal
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15885 (numbers-list height symbol-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15886 "Print a bar graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15887 Used within recursive-graph-body-print function."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15888 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15889
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15890 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15891 (if numbers-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15892 (progn
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15893 (setq from-position (point))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15894 (insert-rectangle
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15895 (column-of-graph height (car numbers-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15896 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15897 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15898 (goto-char from-position)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15899 (forward-char symbol-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15900 (sit-for 0) ; @r{Draw graph column by column.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15901 (recursive-graph-body-print-internal
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15902 (cdr numbers-list) height symbol-width))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15903 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15904 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15905
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15906 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15907 After installation, this expression can be tested; here is a sample:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15908
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15909 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15910 (recursive-graph-body-print '(3 2 5 6 7 5 3 4 6 4 3 2 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15911 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15912
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15913 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15914 Here is what @code{recursive-graph-body-print} produces:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15915
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15916 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15917 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15918 *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15919 ** *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15920 **** *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15921 **** ***
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15922 * *********
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15923 ************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15924 *************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15925 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15926 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15927
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15928 Either of these two functions, @code{graph-body-print} or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15929 @code{recursive-graph-body-print}, create the body of a graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15930
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15931 @node Printed Axes, Line Graph Exercise, recursive-graph-body-print, Readying a Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15932 @section Need for Printed Axes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15933
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15934 A graph needs printed axes, so you can orient yourself. For a do-once
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15935 project, it may be reasonable to draw the axes by hand using Emacs'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15936 Picture mode; but a graph drawing function may be used more than once.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15937
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15938 For this reason, I have written enhancements to the basic
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15939 @code{print-graph-body} function that automatically print labels for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15940 the horizontal and vertical axes. Since the label printing functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15941 do not contain much new material, I have placed their description in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15942 an appendix. @xref{Full Graph, , A Graph with Labelled Axes}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15943
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15944 @node Line Graph Exercise, , Printed Axes, Readying a Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15945 @section Exercise
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15946
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15947 Write a line graph version of the graph printing functions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15948
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15949 @node Emacs Initialization, Debugging, Readying a Graph, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15950 @chapter Your @file{.emacs} File
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15951 @cindex @file{.emacs} file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15952 @cindex Customizing your @file{.emacs} file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15953 @cindex Initialization file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15954
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15955 ``You don't have to like Emacs to like it'' -- this seemingly
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15956 paradoxical statement is the secret of GNU Emacs. The plain, `out of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15957 the box' Emacs is a generic tool. Most people who use it, customize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15958 it to suit themselves.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15959
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15960 GNU Emacs is mostly written in Emacs Lisp; this means that by writing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15961 expressions in Emacs Lisp you can change or extend Emacs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15962
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15963 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15964 * Default Configuration::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15965 * Site-wide Init:: You can write site-wide init files.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15966 * defcustom:: Emacs will write code for you.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15967 * Beginning a .emacs File:: How to write a @code{.emacs file}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15968 * Text and Auto-fill:: Automatically wrap lines.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15969 * Mail Aliases:: Use abbreviations for email addresses.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15970 * Indent Tabs Mode:: Don't use tabs with @TeX{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15971 * Keybindings:: Create some personal keybindings.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15972 * Keymaps:: More about key binding.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15973 * Loading Files:: Load (i.e., evaluate) files automatically.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15974 * Autoload:: Make functions available.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15975 * Simple Extension:: Define a function; bind it to a key.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15976 * X11 Colors:: Colors in version 19 in X.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15977 * Miscellaneous::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15978 * Mode Line:: How to customize your mode line.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15979 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15980
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15981 @node Default Configuration, Site-wide Init, Emacs Initialization, Emacs Initialization
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15982 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15983 @unnumberedsec Emacs' Default Configuration
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15984 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15985
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15986 There are those who appreciate Emacs' default configuration. After
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15987 all, Emacs starts you in C mode when you edit a C file, starts you in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15988 Fortran mode when you edit a Fortran file, and starts you in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15989 Fundamental mode when you edit an unadorned file. This all makes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15990 sense, if you do not know who is going to use Emacs. Who knows what a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15991 person hopes to do with an unadorned file? Fundamental mode is the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15992 right default for such a file, just as C mode is the right default for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15993 editing C code. But when you do know who is going to use Emacs---you,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15994 yourself---then it makes sense to customize Emacs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15995
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15996 For example, I seldom want Fundamental mode when I edit an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15997 otherwise undistinguished file; I want Text mode. This is why I
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15998 customize Emacs: so it suits me.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15999
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16000 You can customize and extend Emacs by writing or adapting a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16001 @file{~/.emacs} file. This is your personal initialization file; its
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16002 contents, written in Emacs Lisp, tell Emacs what to do.@footnote{You
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16003 may also add @file{.el} to @file{~/.emacs} and call it a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16004 @file{~/.emacs.el} file. In the past, you were forbidden to type the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16005 extra keystrokes that the name @file{~/.emacs.el} requires, but now
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16006 you may. The new format is consistent with the Emacs Lisp file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16007 naming conventions; the old format saves typing.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16008
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16009 A @file{~/.emacs} file contains Emacs Lisp code. You can write this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16010 code yourself; or you can use Emacs' @code{customize} feature to write
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16011 the code for you. You can combine your own expressions and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16012 auto-written Customize expressions in your @file{.emacs} file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16013
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16014 (I myself prefer to write my own expressions, except for those,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16015 particularly fonts, that I find easier to manipulate using the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16016 @code{customize} command. I combine the two methods.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16017
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16018 Most of this chapter is about writing expressions yourself. It
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16019 describes a simple @file{.emacs} file; for more information, see
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16020 @ref{Init File, , The Init File, emacs, The GNU Emacs Manual}, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16021 @ref{Init File, , The Init File, elisp, The GNU Emacs Lisp Reference
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16022 Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16023
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16024 @node Site-wide Init, defcustom, Default Configuration, Emacs Initialization
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16025 @section Site-wide Initialization Files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16026
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16027 @cindex @file{default.el} init file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16028 @cindex @file{site-init.el} init file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16029 @cindex @file{site-load.el} init file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16030 In addition to your personal initialization file, Emacs automatically
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16031 loads various site-wide initialization files, if they exist. These
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16032 have the same form as your @file{.emacs} file, but are loaded by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16033 everyone.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16034
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16035 Two site-wide initialization files, @file{site-load.el} and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16036 @file{site-init.el}, are loaded into Emacs and then `dumped' if a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16037 `dumped' version of Emacs is created, as is most common. (Dumped
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16038 copies of Emacs load more quickly. However, once a file is loaded and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16039 dumped, a change to it does not lead to a change in Emacs unless you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16040 load it yourself or re-dump Emacs. @xref{Building Emacs, , Building
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16041 Emacs, elisp, The GNU Emacs Lisp Reference Manual}, and the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16042 @file{INSTALL} file.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16043
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16044 Three other site-wide initialization files are loaded automatically
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16045 each time you start Emacs, if they exist. These are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16046 @file{site-start.el}, which is loaded @emph{before} your @file{.emacs}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16047 file, and @file{default.el}, and the terminal type file, which are both
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16048 loaded @emph{after} your @file{.emacs} file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16049
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16050 Settings and definitions in your @file{.emacs} file will overwrite
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16051 conflicting settings and definitions in a @file{site-start.el} file,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16052 if it exists; but the settings and definitions in a @file{default.el}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16053 or terminal type file will overwrite those in your @file{.emacs} file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16054 (You can prevent interference from a terminal type file by setting
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16055 @code{term-file-prefix} to @code{nil}. @xref{Simple Extension, , A
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16056 Simple Extension}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16057
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16058 @c Rewritten to avoid overfull hbox.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16059 The @file{INSTALL} file that comes in the distribution contains
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16060 descriptions of the @file{site-init.el} and @file{site-load.el} files.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16061
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16062 The @file{loadup.el}, @file{startup.el}, and @file{loaddefs.el} files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16063 control loading. These files are in the @file{lisp} directory of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16064 Emacs distribution and are worth perusing.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16065
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16066 The @file{loaddefs.el} file contains a good many suggestions as to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16067 what to put into your own @file{.emacs} file, or into a site-wide
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16068 initialization file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16069
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16070 @node defcustom, Beginning a .emacs File, Site-wide Init, Emacs Initialization
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16071 @section Specifying Variables using @code{defcustom}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16072 @findex defcustom
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16073
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16074 You can specify variables using @code{defcustom} so that you and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16075 others can then can use Emacs' @code{customize} feature to set their
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16076 values. (You cannot use @code{customize} to write function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16077 definitions; but you can write @code{defuns} in your @file{.emacs}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16078 file. Indeed, you can write any Lisp expression in your @file{.emacs}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16079 file.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16080
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16081 The @code{customize} feature depends on the @code{defcustom} special
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16082 form. Although you can use @code{defvar} or @code{setq} for variables
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16083 that users set, the @code{defcustom} special form is designed for the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16084 job.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16085
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16086 You can use your knowledge of @code{defvar} for writing the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16087 first three arguments for @code{defcustom}. The first argument to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16088 @code{defcustom} is the name of the variable. The second argument is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16089 the variable's initial value, if any; and this value is set only if
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16090 the value has not already been set. The third argument is the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16091 documentation.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16092
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16093 The fourth and subsequent arguments to @code{defcustom} specify types
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16094 and options; these are not featured in @code{defvar}. (These
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16095 arguments are optional.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16096
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16097 Each of these arguments consists of a keyword followed by a value.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16098 Each keyword starts with the character @code{:}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16099
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16100 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16101 For example, the customizable user option variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16102 @code{text-mode-hook} looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16103
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16104 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16105 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16106 (defcustom text-mode-hook nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16107 "Normal hook run when entering Text mode and many related modes."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16108 :type 'hook
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16109 :options '(turn-on-auto-fill flyspell-mode)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16110 :group 'data)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16111 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16112 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16113
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16114 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16115 The name of the variable is @code{text-mode-hook}; it has no default
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16116 value; and its documentation string tells you what it does.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16117
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16118 The @code{:type} keyword tells Emacs what kind of data
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16119 @code{text-mode-hook} should be set to and how to display the value in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16120 a Customization buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16121
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16122 The @code{:options} keyword specifies a suggested list of values for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16123 the variable. Currently, you can use @code{:options} only for a hook.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16124 The list is only a suggestion; it is not exclusive; a person who sets
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16125 the variable may set it to other values; the list shown following the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16126 @code{:options} keyword is intended to offer convenient choices to a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16127 user.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16128
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16129 Finally, the @code{:group} keyword tells the Emacs Customization
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16130 command in which group the variable is located. This tells where to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16131 find it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16132
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16133 For more information, see @ref{Customization, , Writing Customization
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16134 Definitions, elisp, The GNU Emacs Lisp Reference Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16135
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16136 Consider @code{text-mode-hook} as an example.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16137
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16138 There are two ways to customize this variable. You can use the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16139 customization command or write the appropriate expressions yourself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16140
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16141 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16142 Using the customization command, you can type:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16143
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16144 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16145 M-x customize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16146 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16147
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16148 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16149 and find that the group for editing files of data is called `data'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16150 Enter that group. Text Mode Hook is the first member. You can click
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16151 on its various options to set the values. After you click on the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16152 button to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16153
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16154 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16155 Save for Future Sessions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16156 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16157
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16158 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16159 Emacs will write an expression into your @file{.emacs} file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16160 It will look like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16161
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16162 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16163 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16164 (custom-set-variables
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16165 ;; custom-set-variables was added by Custom --
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16166 ;; don't edit or cut/paste it!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16167 ;; Your init file should contain only one such instance.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16168 '(text-mode-hook (quote (turn-on-auto-fill text-mode-hook-identify))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16169 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16170 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16171
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16172 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16173 (The @code{text-mode-hook-identify} function tells
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16174 @code{toggle-text-mode-auto-fill} which buffers are in Text mode.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16175
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16176 In spite of the warning, you certainly may edit, cut, and paste the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16177 expression! I do all time. The purpose of the warning is to scare
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16178 those who do not know what they are doing, so they do not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16179 inadvertently generate an error.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16180
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16181 The @code{custom-set-variables} works somewhat differently than a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16182 @code{setq}. While I have never learned the differences, I do modify
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16183 the @code{custom-set-variables} expressions in my @file{.emacs} file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16184 by hand: I make the changes in what appears to me to be a reasonable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16185 manner and have not had any problems. Others prefer to use the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16186 Customization command and let Emacs do the work for them.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16187
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16188 Another @code{custom-set-@dots{}} function is @code{custom-set-faces}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16189 This function sets the various font faces. Over time, I have set a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16190 considerable number of faces. Some of the time, I re-set them using
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16191 @code{customize}; other times, I simply edit the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16192 @code{custom-set-faces} expression in my @file{.emacs} file itself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16193
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16194 The second way to customize your @code{text-mode-hook} is to set it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16195 yourself in your @file{.emacs} file using code that has nothing to do
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16196 with the @code{custom-set-@dots{}} functions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16197
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16198 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16199 When you do this, and later use @code{customize}, you will see a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16200 message that says
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16201
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16202 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16203 this option has been changed outside the customize buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16204 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16205
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16206 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16207 This message is only a warning. If you click on the button to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16208
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16209 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16210 Save for Future Sessions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16211 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16212
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16213 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16214 Emacs will write a @code{custom-set-@dots{}} expression near the end
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16215 of your @file{.emacs} file that will be evaluated after your
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16216 hand-written expression. It will, therefore, overrule your
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16217 hand-written expression. No harm will be done. When you do this,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16218 however, be careful to remember which expression is active; if you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16219 forget, you may confuse yourself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16220
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16221 So long as you remember where the values are set, you will have no
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16222 trouble. In any event, the values are always set in your
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16223 initialization file, which is usually called @file{.emacs}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16224
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16225 I myself use @code{customize} for hardly anything. Mostly, I write
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16226 expressions myself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16227
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16228 @node Beginning a .emacs File, Text and Auto-fill, defcustom, Emacs Initialization
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16229 @section Beginning a @file{.emacs} File
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16230 @cindex @file{.emacs} file, beginning of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16231
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16232 When you start Emacs, it loads your @file{.emacs} file unless you tell
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16233 it not to by specifying @samp{-q} on the command line. (The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16234 @code{emacs -q} command gives you a plain, out-of-the-box Emacs.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16235
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16236 A @file{.emacs} file contains Lisp expressions. Often, these are no
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16237 more than expressions to set values; sometimes they are function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16238 definitions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16239
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16240 @xref{Init File, , The Init File @file{~/.emacs}, emacs, The GNU Emacs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16241 Manual}, for a short description of initialization files.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16242
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16243 This chapter goes over some of the same ground, but is a walk among
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16244 extracts from a complete, long-used @file{.emacs} file---my own.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16245
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16246 The first part of the file consists of comments: reminders to myself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16247 By now, of course, I remember these things, but when I started, I did
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16248 not.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16249
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16250 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16251 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16252 ;;;; Bob's .emacs file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16253 ; Robert J. Chassell
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16254 ; 26 September 1985
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16255 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16256 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16257
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16258 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16259 Look at that date! I started this file a long time ago. I have been
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16260 adding to it ever since.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16261
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16262 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16263 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16264 ; Each section in this file is introduced by a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16265 ; line beginning with four semicolons; and each
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16266 ; entry is introduced by a line beginning with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16267 ; three semicolons.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16268 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16269 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16270
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16271 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16272 This describes the usual conventions for comments in Emacs Lisp.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16273 Everything on a line that follows a semicolon is a comment. Two,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16274 three, and four semicolons are used as section and subsection
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16275 markers. (@xref{Comments, ,, elisp, The GNU Emacs Lisp Reference
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16276 Manual}, for more about comments.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16277
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16278 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16279 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16280 ;;;; The Help Key
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16281 ; Control-h is the help key;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16282 ; after typing control-h, type a letter to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16283 ; indicate the subject about which you want help.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16284 ; For an explanation of the help facility,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16285 ; type control-h two times in a row.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16286 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16287 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16288
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16289 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16290 Just remember: type @kbd{C-h} two times for help.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16291
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16292 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16293 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16294 ; To find out about any mode, type control-h m
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16295 ; while in that mode. For example, to find out
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16296 ; about mail mode, enter mail mode and then type
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16297 ; control-h m.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16298 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16299 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16300
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16301 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16302 `Mode help', as I call this, is very helpful. Usually, it tells you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16303 all you need to know.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16304
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16305 Of course, you don't need to include comments like these in your
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16306 @file{.emacs} file. I included them in mine because I kept forgetting
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16307 about Mode help or the conventions for comments---but I was able to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16308 remember to look here to remind myself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16309
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16310 @node Text and Auto-fill, Mail Aliases, Beginning a .emacs File, Emacs Initialization
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16311 @section Text and Auto Fill Mode
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16312
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16313 Now we come to the part that `turns on' Text mode and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16314 Auto Fill mode.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16315
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16316 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16317 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16318 ;;; Text mode and Auto Fill mode
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16319 ; The next three lines put Emacs into Text mode
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16320 ; and Auto Fill mode, and are for writers who
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16321 ; want to start writing prose rather than code.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16322
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16323 (setq default-major-mode 'text-mode)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16324 (add-hook 'text-mode-hook 'text-mode-hook-identify)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16325 (add-hook 'text-mode-hook 'turn-on-auto-fill)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16326 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16327 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16328
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16329 Here is the first part of this @file{.emacs} file that does something
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16330 besides remind a forgetful human!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16331
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16332 The first of the two lines in parentheses tells Emacs to turn on Text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16333 mode when you find a file, @emph{unless} that file should go into some
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16334 other mode, such as C mode.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16335
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16336 @cindex Per-buffer, local variables list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16337 @cindex Local variables list, per-buffer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16338 @cindex Automatic mode selection
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16339 @cindex Mode selection, automatic
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16340 When Emacs reads a file, it looks at the extension to the file name,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16341 if any. (The extension is the part that comes after a @samp{.}.) If
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16342 the file ends with a @samp{.c} or @samp{.h} extension then Emacs turns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16343 on C mode. Also, Emacs looks at first nonblank line of the file; if
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16344 the line says @w{@samp{-*- C -*-}}, Emacs turns on C mode. Emacs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16345 possesses a list of extensions and specifications that it uses
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16346 automatically. In addition, Emacs looks near the last page for a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16347 per-buffer, ``local variables list'', if any.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16348
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16349 @ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16350 @xref{Choosing Modes, , How Major Modes are Chosen, emacs, The GNU
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16351 Emacs Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16352
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16353 @xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16354 Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16355 @end ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16356 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16357 See sections ``How Major Modes are Chosen'' and ``Local Variables in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16358 Files'' in @cite{The GNU Emacs Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16359 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16360
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16361 Now, back to the @file{.emacs} file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16362
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16363 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16364 Here is the line again; how does it work?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16365
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16366 @cindex Text Mode turned on
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16367 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16368 (setq default-major-mode 'text-mode)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16369 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16370
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16371 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16372 This line is a short, but complete Emacs Lisp expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16373
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16374 We are already familiar with @code{setq}. It sets the following variable,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16375 @code{default-major-mode}, to the subsequent value, which is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16376 @code{text-mode}. The single quote mark before @code{text-mode} tells
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16377 Emacs to deal directly with the @code{text-mode} variable, not with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16378 whatever it might stand for. @xref{set & setq, , Setting the Value of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16379 a Variable}, for a reminder of how @code{setq} works. The main point
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16380 is that there is no difference between the procedure you use to set
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16381 a value in your @file{.emacs} file and the procedure you use anywhere
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16382 else in Emacs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16383
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16384 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16385 Here are the next two lines:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16386
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16387 @cindex Auto Fill mode turned on
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16388 @findex add-hook
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16389 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16390 (add-hook 'text-mode-hook 'text-mode-hook-identify)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16391 (add-hook 'text-mode-hook 'turn-on-auto-fill)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16392 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16393
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16394 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16395 In these two lines, the @code{add-hook} command first adds
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16396 @code{text-mode-hook-identify} to the variable called
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16397 @code{text-mode-hook} and then adds @code{turn-on-auto-fill} to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16398 variable.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16399
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16400 @code{turn-on-auto-fill} is the name of a program, that, you guessed
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16401 it!, turns on Auto Fill mode. @code{text-mode-hook-identify} is a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16402 function that tells @code{toggle-text-mode-auto-fill} which buffers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16403 are in Text mode.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16404
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16405 Every time Emacs turns on Text mode, Emacs runs the commands `hooked'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16406 onto Text mode. So every time Emacs turns on Text mode, Emacs also
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16407 turns on Auto Fill mode.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16408
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16409 In brief, the first line causes Emacs to enter Text mode when you edit
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16410 a file, unless the file name extension, first non-blank line, or local
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16411 variables tell Emacs otherwise.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16412
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16413 Text mode among other actions, sets the syntax table to work
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16414 conveniently for writers. In Text mode, Emacs considers an apostrophe
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16415 as part of a word like a letter; but Emacs does not consider a period
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16416 or a space as part of a word. Thus, @kbd{M-f} moves you over
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16417 @samp{it's}. On the other hand, in C mode, @kbd{M-f} stops just after
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16418 the @samp{t} of @samp{it's}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16419
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16420 The second and third lines causes Emacs to turn on Auto Fill mode when
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16421 it turns on Text mode. In Auto Fill mode, Emacs automatically breaks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16422 a line that is too wide and brings the excessively wide part of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16423 line down to the next line. Emacs breaks lines between words, not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16424 within them.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16425
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16426 When Auto Fill mode is turned off, lines continue to the right as you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16427 type them. Depending on how you set the value of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16428 @code{truncate-lines}, the words you type either disappear off the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16429 right side of the screen, or else are shown, in a rather ugly and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16430 unreadable manner, as a continuation line on the screen.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16431
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16432 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16433 In addition, in this part of my @file{.emacs} file, I tell the Emacs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16434 fill commands to insert two spaces after a colon:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16435
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16436 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16437 (setq colon-double-space t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16438 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16439
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16440 @node Mail Aliases, Indent Tabs Mode, Text and Auto-fill, Emacs Initialization
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16441 @section Mail Aliases
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16442
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16443 Here is a @code{setq} that `turns on' mail aliases, along with more
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16444 reminders.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16445
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16446 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16447 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16448 ;;; Mail mode
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16449 ; To enter mail mode, type `C-x m'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16450 ; To enter RMAIL (for reading mail),
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16451 ; type `M-x rmail'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16452
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16453 (setq mail-aliases t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16454 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16455 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16456
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16457 @cindex Mail aliases
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16458 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16459 This @code{setq} command sets the value of the variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16460 @code{mail-aliases} to @code{t}. Since @code{t} means true, the line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16461 says, in effect, ``Yes, use mail aliases.''
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16462
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16463 Mail aliases are convenient short names for long email addresses or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16464 for lists of email addresses. The file where you keep your `aliases'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16465 is @file{~/.mailrc}. You write an alias like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16466
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16467 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16468 alias geo george@@foobar.wiz.edu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16469 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16470
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16471 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16472 When you write a message to George, address it to @samp{geo}; the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16473 mailer will automatically expand @samp{geo} to the full address.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16474
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16475 @node Indent Tabs Mode, Keybindings, Mail Aliases, Emacs Initialization
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16476 @section Indent Tabs Mode
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16477 @cindex Tabs, preventing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16478 @findex indent-tabs-mode
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16479
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16480 By default, Emacs inserts tabs in place of multiple spaces when it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16481 formats a region. (For example, you might indent many lines of text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16482 all at once with the @code{indent-region} command.) Tabs look fine on
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16483 a terminal or with ordinary printing, but they produce badly indented
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16484 output when you use @TeX{} or Texinfo since @TeX{} ignores tabs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16485
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16486 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16487 The following turns off Indent Tabs mode:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16488
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16489 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16490 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16491 ;;; Prevent Extraneous Tabs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16492 (setq-default indent-tabs-mode nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16493 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16494 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16495
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16496 Note that this line uses @code{setq-default} rather than the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16497 @code{setq} command that we have seen before. The @code{setq-default}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16498 command sets values only in buffers that do not have their own local
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16499 values for the variable.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16501 @ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16502 @xref{Just Spaces, , Tabs vs. Spaces, emacs, The GNU Emacs Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16503
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16504 @xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16505 Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16506 @end ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16507 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16508 See sections ``Tabs vs.@: Spaces'' and ``Local Variables in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16509 Files'' in @cite{The GNU Emacs Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16510 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16511
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16512 @node Keybindings, Keymaps, Indent Tabs Mode, Emacs Initialization
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16513 @section Some Keybindings
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16514
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16515 Now for some personal keybindings:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16516
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16517 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16518 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16519 ;;; Compare windows
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16520 (global-set-key "\C-cw" 'compare-windows)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16521 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16522 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16523
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16524 @findex compare-windows
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16525 @code{compare-windows} is a nifty command that compares the text in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16526 your current window with text in the next window. It makes the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16527 comparison by starting at point in each window, moving over text in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16528 each window as far as they match. I use this command all the time.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16529
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16530 This also shows how to set a key globally, for all modes.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16531
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16532 @cindex Setting a key globally
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16533 @cindex Global set key
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16534 @cindex Key setting globally
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16535 @findex global-set-key
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16536 The command is @code{global-set-key}. It is followed by the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16537 keybinding. In a @file{.emacs} file, the keybinding is written as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16538 shown: @code{\C-c} stands for `control-c', which means `press the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16539 control key and the @kbd{c} key at the same time'. The @code{w} means
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16540 `press the @kbd{w} key'. The keybinding is surrounded by double
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16541 quotation marks. In documentation, you would write this as @kbd{C-c
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16542 w}. (If you were binding a @key{META} key, such as @kbd{M-c}, rather
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16543 than a @key{CTL} key, you would write @code{\M-c}. @xref{Init
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16544 Rebinding, , Rebinding Keys in Your Init File, emacs, The GNU Emacs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16545 Manual}, for details.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16546
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16547 The command invoked by the keys is @code{compare-windows}. Note that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16548 @code{compare-windows} is preceded by a single quote; otherwise, Emacs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16549 would first try to evaluate the symbol to determine its value.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16550
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16551 These three things, the double quotation marks, the backslash before
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16552 the @samp{C}, and the single quote mark are necessary parts of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16553 keybinding that I tend to forget. Fortunately, I have come to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16554 remember that I should look at my existing @file{.emacs} file, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16555 adapt what is there.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16556
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16557 As for the keybinding itself: @kbd{C-c w}. This combines the prefix
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16558 key, @kbd{C-c}, with a single character, in this case, @kbd{w}. This
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16559 set of keys, @kbd{C-c} followed by a single character, is strictly
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16560 reserved for individuals' own use. (I call these `own' keys, since
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16561 these are for my own use.) You should always be able to create such a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16562 keybinding for your own use without stomping on someone else's
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16563 keybinding. If you ever write an extension to Emacs, please avoid
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16564 taking any of these keys for public use. Create a key like @kbd{C-c
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16565 C-w} instead. Otherwise, we will run out of `own' keys.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16566
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16567 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16568 Here is another keybinding, with a comment:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16569
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16570 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16571 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16572 ;;; Keybinding for `occur'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16573 ; I use occur a lot, so let's bind it to a key:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16574 (global-set-key "\C-co" 'occur)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16575 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16576 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16577
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16578 @findex occur
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16579 The @code{occur} command shows all the lines in the current buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16580 that contain a match for a regular expression. Matching lines are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16581 shown in a buffer called @file{*Occur*}. That buffer serves as a menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16582 to jump to occurrences.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16583
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16584 @findex global-unset-key
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16585 @cindex Unbinding key
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16586 @cindex Key unbinding
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16587 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16588 Here is how to unbind a key, so it does not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16589 work:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16590
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16591 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16592 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16593 ;;; Unbind `C-x f'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16594 (global-unset-key "\C-xf")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16595 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16596 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16597
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16598 There is a reason for this unbinding: I found I inadvertently typed
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16599 @w{@kbd{C-x f}} when I meant to type @kbd{C-x C-f}. Rather than find a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16600 file, as I intended, I accidentally set the width for filled text,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16601 almost always to a width I did not want. Since I hardly ever reset my
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16602 default width, I simply unbound the key.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16603
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16604 @findex list-buffers, @r{rebound}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16605 @findex buffer-menu, @r{bound to key}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16606 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16607 The following rebinds an existing key:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16608
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16609 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16610 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16611 ;;; Rebind `C-x C-b' for `buffer-menu'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16612 (global-set-key "\C-x\C-b" 'buffer-menu)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16613 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16614 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16615
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16616 By default, @kbd{C-x C-b} runs the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16617 @code{list-buffers} command. This command lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16618 your buffers in @emph{another} window. Since I
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16619 almost always want to do something in that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16620 window, I prefer the @code{buffer-menu}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16621 command, which not only lists the buffers,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16622 but moves point into that window.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16623
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16624 @node Keymaps, Loading Files, Keybindings, Emacs Initialization
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16625 @section Keymaps
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16626 @cindex Keymaps
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16627 @cindex Rebinding keys
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16628
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16629 Emacs uses @dfn{keymaps} to record which keys call which commands.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16630 When you use @code{global-set-key} to set the keybinding for a single
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16631 command in all parts of Emacs, you are specifying the keybinding in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16632 @code{current-global-map}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16633
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16634 Specific modes, such as C mode or Text mode, have their own keymaps;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16635 the mode-specific keymaps override the global map that is shared by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16636 all buffers.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16637
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16638 The @code{global-set-key} function binds, or rebinds, the global
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16639 keymap. For example, the following binds the key @kbd{C-x C-b} to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16640 function @code{buffer-menu}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16641
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16642 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16643 (global-set-key "\C-x\C-b" 'buffer-menu)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16644 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16645
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16646 Mode-specific keymaps are bound using the @code{define-key} function,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16647 which takes a specific keymap as an argument, as well as the key and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16648 the command. For example, my @file{.emacs} file contains the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16649 following expression to bind the @code{texinfo-insert-@@group} command
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16650 to @kbd{C-c C-c g}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16651
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16652 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16653 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16654 (define-key texinfo-mode-map "\C-c\C-cg" 'texinfo-insert-@@group)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16655 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16656 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16657
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16658 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16659 The @code{texinfo-insert-@@group} function itself is a little extension
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16660 to Texinfo mode that inserts @samp{@@group} into a Texinfo file. I
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16661 use this command all the time and prefer to type the three strokes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16662 @kbd{C-c C-c g} rather than the six strokes @kbd{@@ g r o u p}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16663 (@samp{@@group} and its matching @samp{@@end group} are commands that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16664 keep all enclosed text together on one page; many multi-line examples
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16665 in this book are surrounded by @samp{@@group @dots{} @@end group}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16666
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16667 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16668 Here is the @code{texinfo-insert-@@group} function definition:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16669
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16670 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16671 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16672 (defun texinfo-insert-@@group ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16673 "Insert the string @@group in a Texinfo buffer."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16674 (interactive)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16675 (beginning-of-line)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16676 (insert "@@group\n"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16677 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16678 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16679
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16680 (Of course, I could have used Abbrev mode to save typing, rather than
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16681 write a function to insert a word; but I prefer key strokes consistent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16682 with other Texinfo mode key bindings.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16683
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16684 You will see numerous @code{define-key} expressions in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16685 @file{loaddefs.el} as well as in the various mode libraries, such as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16686 @file{cc-mode.el} and @file{lisp-mode.el}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16687
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16688 @xref{Key Bindings, , Customizing Key Bindings, emacs, The GNU Emacs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16689 Manual}, and @ref{Keymaps, , Keymaps, elisp, The GNU Emacs Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16690 Reference Manual}, for more information about keymaps.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16691
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16692 @node Loading Files, Autoload, Keymaps, Emacs Initialization
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16693 @section Loading Files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16694 @cindex Loading files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16695 @c findex load
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16696
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16697 Many people in the GNU Emacs community have written extensions to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16698 Emacs. As time goes by, these extensions are often included in new
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16699 releases. For example, the Calendar and Diary packages are now part
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16700 of the standard GNU Emacs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16701
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16702 (Calc, which I consider a vital part of Emacs, would be part of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16703 standard distribution except that it was so large it was packaged
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16704 separately and no one has changed that.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16705
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16706 You can use a @code{load} command to evaluate a complete file and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16707 thereby install all the functions and variables in the file into Emacs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16708 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16709
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16710 @c (auto-compression-mode t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16711
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16712 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16713 (load "~/emacs/slowsplit")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16714 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16715
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16716 This evaluates, i.e.@: loads, the @file{slowsplit.el} file or if it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16717 exists, the faster, byte compiled @file{slowsplit.elc} file from the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16718 @file{emacs} sub-directory of your home directory. The file contains
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16719 the function @code{split-window-quietly}, which John Robinson wrote in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16720 1989.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16721
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16722 The @code{split-window-quietly} function splits a window with the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16723 minimum of redisplay. I installed it in 1989 because it worked well
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16724 with the slow 1200 baud terminals I was then using. Nowadays, I only
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16725 occasionally come across such a slow connection, but I continue to use
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16726 the function because I like the way it leaves the bottom half of a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16727 buffer in the lower of the new windows and the top half in the upper
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16728 window.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16729
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16730 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16731 To replace the key binding for the default
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16732 @code{split-window-vertically}, you must also unset that key and bind
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16733 the keys to @code{split-window-quietly}, like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16734
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16735 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16736 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16737 (global-unset-key "\C-x2")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16738 (global-set-key "\C-x2" 'split-window-quietly)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16739 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16740 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16741
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16742 @vindex load-path
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16743 If you load many extensions, as I do, then instead of specifying the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16744 exact location of the extension file, as shown above, you can specify
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16745 that directory as part of Emacs' @code{load-path}. Then, when Emacs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16746 loads a file, it will search that directory as well as its default
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16747 list of directories. (The default list is specified in @file{paths.h}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16748 when Emacs is built.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16749
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16750 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16751 The following command adds your @file{~/emacs} directory to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16752 existing load path:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16753
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16754 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16755 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16756 ;;; Emacs Load Path
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16757 (setq load-path (cons "~/emacs" load-path))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16758 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16759 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16760
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16761 Incidentally, @code{load-library} is an interactive interface to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16762 @code{load} function. The complete function looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16763
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16764 @findex load-library
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16765 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16766 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16767 (defun load-library (library)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16768 "Load the library named LIBRARY.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16769 This is an interface to the function `load'."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16770 (interactive "sLoad library: ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16771 (load library))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16772 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16773 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16774
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16775 The name of the function, @code{load-library}, comes from the use of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16776 `library' as a conventional synonym for `file'. The source for the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16777 @code{load-library} command is in the @file{files.el} library.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16778
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16779 Another interactive command that does a slightly different job is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16780 @code{load-file}. @xref{Lisp Libraries, , Libraries of Lisp Code for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16781 Emacs, emacs, The GNU Emacs Manual}, for information on the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16782 distinction between @code{load-library} and this command.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16783
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16784 @node Autoload, Simple Extension, Loading Files, Emacs Initialization
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16785 @section Autoloading
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16786 @findex autoload
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16787
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16788 Instead of installing a function by loading the file that contains it,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16789 or by evaluating the function definition, you can make the function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16790 available but not actually install it until it is first called. This
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16791 is called @dfn{autoloading}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16792
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16793 When you execute an autoloaded function, Emacs automatically evaluates
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16794 the file that contains the definition, and then calls the function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16795
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16796 Emacs starts quicker with autoloaded functions, since their libraries
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16797 are not loaded right away; but you need to wait a moment when you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16798 first use such a function, while its containing file is evaluated.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16799
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16800 Rarely used functions are frequently autoloaded. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16801 @file{loaddefs.el} library contains hundreds of autoloaded functions,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16802 from @code{bookmark-set} to @code{wordstar-mode}. Of course, you may
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16803 come to use a `rare' function frequently. When you do, you should
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16804 load that function's file with a @code{load} expression in your
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16805 @file{.emacs} file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16806
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16807 In my @file{.emacs} file for Emacs version 21, I load 12 libraries
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16808 that contain functions that would otherwise be autoloaded. (Actually,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16809 it would have been better to include these files in my `dumped' Emacs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16810 when I built it, but I forgot. @xref{Building Emacs, , Building
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16811 Emacs, elisp, The GNU Emacs Lisp Reference Manual}, and the @file{INSTALL}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16812 file for more about dumping.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16813
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16814 You may also want to include autoloaded expressions in your @file{.emacs}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16815 file. @code{autoload} is a built-in function that takes up to five
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16816 arguments, the final three of which are optional. The first argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16817 is the name of the function to be autoloaded; the second is the name
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16818 of the file to be loaded. The third argument is documentation for the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16819 function, and the fourth tells whether the function can be called
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16820 interactively. The fifth argument tells what type of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16821 object---@code{autoload} can handle a keymap or macro as well as a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16822 function (the default is a function).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16823
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16824 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16825 Here is a typical example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16826
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16827 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16828 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16829 (autoload 'html-helper-mode
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16830 "html-helper-mode" "Edit HTML documents" t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16831 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16832 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16833
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16834 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16835 (@code{html-helper-mode} is an alternative to @code{html-mode}, which
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16836 is a standard part of the distribution).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16837
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16838 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16839 This expression autoloads the @code{html-helper-mode} function. It
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16840 takes it from the @file{html-helper-mode.el} file (or from the byte
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16841 compiled file @file{html-helper-mode.elc}, if it exists.) The file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16842 must be located in a directory specified by @code{load-path}. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16843 documentation says that this is a mode to help you edit documents
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16844 written in the HyperText Markup Language. You can call this mode
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16845 interactively by typing @kbd{M-x html-helper-mode}. (You need to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16846 duplicate the function's regular documentation in the autoload
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16847 expression because the regular function is not yet loaded, so its
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16848 documentation is not available.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16849
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16850 @xref{Autoload, , Autoload, elisp, The GNU Emacs Lisp Reference
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16851 Manual}, for more information.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16852
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16853 @node Simple Extension, X11 Colors, Autoload, Emacs Initialization
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16854 @section A Simple Extension: @code{line-to-top-of-window}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16855 @findex line-to-top-of-window
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16856 @cindex Simple extension in @file{.emacs} file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16857
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16858 Here is a simple extension to Emacs that moves the line point is on to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16859 the top of the window. I use this all the time, to make text easier
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16860 to read.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16861
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16862 You can put the following code into a separate file and then load it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16863 from your @file{.emacs} file, or you can include it within your
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16864 @file{.emacs} file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16865
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16866 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16867 Here is the definition:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16868
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16869 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16870 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16871 ;;; Line to top of window;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16872 ;;; replace three keystroke sequence C-u 0 C-l
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16873 (defun line-to-top-of-window ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16874 "Move the line point is on to top of window."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16875 (interactive)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16876 (recenter 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16877 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16878 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16879
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16880 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16881 Now for the keybinding.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16882
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16883 Nowadays, function keys as well as mouse button events and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16884 non-@sc{ascii} characters are written within square brackets, without
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16885 quotation marks. (In Emacs version 18 and before, you had to write
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16886 different function key bindings for each different make of terminal.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16887
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16888 I bind @code{line-to-top-of-window} to my @key{F6} function key like
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16889 this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16890
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16891 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16892 (global-set-key [f6] 'line-to-top-of-window)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16893 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16894
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16895 For more information, see @ref{Init Rebinding, , Rebinding Keys in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16896 Your Init File, emacs, The GNU Emacs Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16897
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16898 @cindex Conditional 'twixt two versions of Emacs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16899 @cindex Version of Emacs, choosing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16900 @cindex Emacs version, choosing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16901 If you run two versions of GNU Emacs, such as versions 20 and 21, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16902 use one @file{.emacs} file, you can select which code to evaluate with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16903 the following conditional:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16904
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16905 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16906 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16907 (cond
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16908 ((string-equal (number-to-string 20) (substring (emacs-version) 10 12))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16909 ;; evaluate version 20 code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16910 ( @dots{} ))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16911 ((string-equal (number-to-string 21) (substring (emacs-version) 10 12))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16912 ;; evaluate version 21 code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16913 ( @dots{} )))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16914 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16915 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16916
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16917 For example, in contrast to version 20, version 21 blinks its cursor
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16918 by default. I hate such blinking, as well as some other features in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16919 version 21, so I placed the following in my @file{.emacs}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16920 file@footnote{When I start instances of Emacs that do not load my
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16921 @file{.emacs} file or any site file, I also turn off blinking:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16922
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16923 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16924 emacs -q --no-site-file -eval '(blink-cursor-mode nil)'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16925 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16926 }:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16927
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16928 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16929 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16930 (if (string-equal "21" (substring (emacs-version) 10 12))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16931 (progn
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16932 (blink-cursor-mode 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16933 ;; Insert newline when you press `C-n' (next-line)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16934 ;; at the end of the buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16935 (setq next-line-add-newlines t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16936 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16937 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16938 ;; Turn on image viewing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16939 (auto-image-file-mode t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16940 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16941 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16942 ;; Turn on menu bar (this bar has text)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16943 ;; (Use numeric argument to turn on)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16944 (menu-bar-mode 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16945 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16946 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16947 ;; Turn off tool bar (this bar has icons)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16948 ;; (Use numeric argument to turn on)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16949 (tool-bar-mode nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16950 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16951 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16952 ;; Turn off tooltip mode for tool bar
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16953 ;; (This mode causes icon explanations to pop up)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16954 ;; (Use numeric argument to turn on)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16955 (tooltip-mode nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16956 ;; If tooltips turned on, make tips appear promptly
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16957 (setq tooltip-delay 0.1) ; default is one second
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16958 ))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16959 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16960 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16961
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16962 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16963 (You will note that instead of typing @code{(number-to-string 21)}, I
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16964 decided to save typing and wrote `21' as a string, @code{"21"}, rather
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16965 than convert it from an integer to a string. In this instance, this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16966 expression is better than the longer, but more general
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16967 @code{(number-to-string 21)}. However, if you do not know ahead of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16968 time what type of information will be returned, then the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16969 @code{number-to-string} function will be needed.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16970
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16971 @node X11 Colors, Miscellaneous, Simple Extension, Emacs Initialization
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16972 @section X11 Colors
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16973
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16974 You can specify colors when you use Emacs with the MIT X Windowing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16975 system.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16976
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16977 I dislike the default colors and specify my own.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16978
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16979 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16980 Here are the expressions in my @file{.emacs}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16981 file that set values:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16982
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16983 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16984 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16985 ;; Set cursor color
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16986 (set-cursor-color "white")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16987
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16988 ;; Set mouse color
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16989 (set-mouse-color "white")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16990
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16991 ;; Set foreground and background
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16992 (set-foreground-color "white")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16993 (set-background-color "darkblue")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16994 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16995
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16996 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16997 ;;; Set highlighting colors for isearch and drag
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16998 (set-face-foreground 'highlight "white")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16999 (set-face-background 'highlight "blue")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17000 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17001
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17002 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17003 (set-face-foreground 'region "cyan")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17004 (set-face-background 'region "blue")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17005 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17006
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17007 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17008 (set-face-foreground 'secondary-selection "skyblue")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17009 (set-face-background 'secondary-selection "darkblue")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17010 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17011
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17012 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17013 ;; Set calendar highlighting colors
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17014 (setq calendar-load-hook
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17015 '(lambda ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17016 (set-face-foreground 'diary-face "skyblue")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17017 (set-face-background 'holiday-face "slate blue")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17018 (set-face-foreground 'holiday-face "white")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17019 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17020 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17021
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17022 The various shades of blue soothe my eye and prevent me from seeing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17023 the screen flicker.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17024
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17025 Alternatively, I could have set my specifications in various X
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17026 initialization files. For example, I could set the foreground,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17027 background, cursor, and pointer (i.e., mouse) colors in my
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17028 @file{~/.Xresources} file like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17029
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17030 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17031 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17032 Emacs*foreground: white
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17033 Emacs*background: darkblue
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17034 Emacs*cursorColor: white
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17035 Emacs*pointerColor: white
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17036 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17037 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17038
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17039 In any event, since it is not part of Emacs, I set the root color of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17040 my X window in my @file{~/.xinitrc} file, like this@footnote{I
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17041 occasionally run more modern window managers, such as Sawfish with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17042 GNOME, Enlightenment, SCWM, or KDE; in those cases, I often specify an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17043 image rather than a plain color.}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17044
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17045 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17046 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17047 # I use TWM for window manager.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17048 xsetroot -solid Navy -fg white &
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17049 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17050 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17051
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17052 @node Miscellaneous, Mode Line, X11 Colors, Emacs Initialization
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17053 @section Miscellaneous Settings for a @file{.emacs} File
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17054
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17055 Here are a few miscellaneous settings:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17056 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17057
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17058 @itemize @minus
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17059 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17060 Set the shape and color of the mouse cursor:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17061 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17062 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17063 ; Cursor shapes are defined in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17064 ; `/usr/include/X11/cursorfont.h';
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17065 ; for example, the `target' cursor is number 128;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17066 ; the `top_left_arrow' cursor is number 132.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17067 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17068
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17069 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17070 (let ((mpointer (x-get-resource "*mpointer"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17071 "*emacs*mpointer")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17072 ;; If you have not set your mouse pointer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17073 ;; then set it, otherwise leave as is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17074 (if (eq mpointer nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17075 (setq mpointer "132")) ; top_left_arrow
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17076 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17077 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17078 (setq x-pointer-shape (string-to-int mpointer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17079 (set-mouse-color "white"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17080 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17081 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17082 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17083
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17084 @node Mode Line, , Miscellaneous, Emacs Initialization
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17085 @section A Modified Mode Line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17086 @vindex default-mode-line-format
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17087 @cindex Mode line format
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17088
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17089 Finally, a feature I really like: a modified mode line.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17090
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17091 When I work over a network, I forget which machine I am using. Also,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17092 I tend to I lose track of where I am, and which line point is on.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17093
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17094 So I reset my mode line to look like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17095
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17096 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17097 -:-- foo.texi rattlesnake:/home/bob/ Line 1 (Texinfo Fill) Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17098 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17099
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17100 I am visiting a file called @file{foo.texi}, on my machine
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17101 @file{rattlesnake} in my @file{/home/bob} buffer. I am on line 1, in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17102 Texinfo mode, and am at the top of the buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17103
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17104 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17105 My @file{.emacs} file has a section that looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17106
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17107 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17108 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17109 ;; Set a Mode Line that tells me which machine, which directory,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17110 ;; and which line I am on, plus the other customary information.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17111 (setq default-mode-line-format
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17112 (quote
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17113 (#("-" 0 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17114 (help-echo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17115 "mouse-1: select window, mouse-2: delete others ..."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17116 mode-line-mule-info
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17117 mode-line-modified
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17118 mode-line-frame-identification
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17119 " "
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17120 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17121 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17122 mode-line-buffer-identification
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17123 " "
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17124 (:eval (substring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17125 (system-name) 0 (string-match "\\..+" (system-name))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17126 ":"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17127 default-directory
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17128 #(" " 0 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17129 (help-echo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17130 "mouse-1: select window, mouse-2: delete others ..."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17131 (line-number-mode " Line %l ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17132 global-mode-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17133 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17134 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17135 #(" %[(" 0 6
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17136 (help-echo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17137 "mouse-1: select window, mouse-2: delete others ..."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17138 (:eval (mode-line-mode-name))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17139 mode-line-process
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17140 minor-mode-alist
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17141 #("%n" 0 2 (help-echo "mouse-2: widen" local-map (keymap ...)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17142 ")%] "
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17143 (-3 . "%P")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17144 ;; "-%-"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17145 )))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17146 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17147 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17148
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17149 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17150 Here, I redefine the default mode line. Most of the parts are from
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17151 the original; but I make a few changes. I set the @emph{default} mode
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17152 line format so as to permit various modes, such as Info, to override
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17153 it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17154
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17155 Many elements in the list are self-explanatory:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17156 @code{mode-line-modified} is a variable that tells whether the buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17157 has been modified, @code{mode-name} tells the name of the mode, and so
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17158 on. However, the format looks complicated because of two features we
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17159 have not discussed.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17160
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17161 The first string in the mode line is a dash or hyphen, @samp{-}. In
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17162 the old days, it would have been specified simply as @code{"-"}. But
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17163 nowadays, Emacs can add properties to a string, such as highlighting
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17164 or, as in this case, a help feature. If you place your mouse cursor
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17165 over the hyphen, some help information appears (By default, you must
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17166 wait one second before the information appears. You can change that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17167 timing by changing the value of @code{tooltip-delay}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17168
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17169 @need 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17170 The new string format has a special syntax:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17171
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17172 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17173 #("-" 0 1 (help-echo "mouse-1: select window, ..."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17174 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17175
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17176 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17177 The @code{#(} begins a list. The first element of the list is the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17178 string itself, just one @samp{-}. The second and third
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17179 elements specify the range over which the fourth element applies. A
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17180 range starts @emph{after} a character, so a zero means the range
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17181 starts just before the first character; a 1 means that the range ends
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17182 just after the first character. The third element is the property for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17183 the range. It consists of a property list, a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17184 property name, in this case, @samp{help-echo}, followed by a value, in this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17185 case, a string. The second, third, and fourth elements of this new
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17186 string format can be repeated.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17187
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17188 @xref{Text Props and Strings, , Text Properties in String, elisp, The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17189 GNU Emacs Lisp Reference Manual}, and see @ref{Mode Line Format, , Mode
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17190 Line Format, elisp, The GNU Emacs Lisp Reference Manual}, for more
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17191 information.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17192
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17193 @code{mode-line-buffer-identification}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17194 displays the current buffer name. It is a list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17195 beginning @code{(#("%12b" 0 4 @dots{}}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17196 The @code{#(} begins the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17197
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17198 The @samp{"%12b"} displays the current buffer name, using the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17199 @code{buffer-name} function with which we are familiar; the `12'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17200 specifies the maximum number of characters that will be displayed.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17201 When a name has fewer characters, whitespace is added to fill out to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17202 this number. (Buffer names can and often should be longer than 12
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17203 characters; this length works well in a typical 80 column wide
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17204 window.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17205
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17206 @code{:eval} is a new feature in GNU Emacs version 21. It says to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17207 evaluate the following form and use the result as a string to display.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17208 In this case, the expression displays the first component of the full
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17209 system name. The end of the first component is a @samp{.} (`period'),
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17210 so I use the @code{string-match} function to tell me the length of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17211 first component. The substring from the zeroth character to that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17212 length is the name of the machine.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17213
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17214 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17215 This is the expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17216
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17217 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17218 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17219 (:eval (substring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17220 (system-name) 0 (string-match "\\..+" (system-name))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17221 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17222 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17223
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17224 @samp{%[} and @samp{%]} cause a pair of square brackets
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17225 to appear for each recursive editing level. @samp{%n} says `Narrow'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17226 when narrowing is in effect. @samp{%P} tells you the percentage of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17227 the buffer that is above the bottom of the window, or `Top', `Bottom',
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17228 or `All'. (A lower case @samp{p} tell you the percentage above the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17229 @emph{top} of the window.) @samp{%-} inserts enough dashes to fill
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17230 out the line.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17231
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17232 Remember, ``You don't have to like Emacs to like it'' --- your own
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17233 Emacs can have different colors, different commands, and different
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17234 keys than a default Emacs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17235
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17236 On the other hand, if you want to bring up a plain `out of the box'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17237 Emacs, with no customization, type:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17238
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17239 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17240 emacs -q
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17241 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17242
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17243 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17244 This will start an Emacs that does @emph{not} load your
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17245 @file{~/.emacs} initialization file. A plain, default Emacs. Nothing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17246 more.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17247
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17248 @node Debugging, Conclusion, Emacs Initialization, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17249 @chapter Debugging
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17250 @cindex debugging
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17251
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17252 GNU Emacs has two debuggers, @code{debug} and @code{edebug}. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17253 first is built into the internals of Emacs and is always with you;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17254 the second requires that you instrument a function before you can use it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17255
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17256 Both debuggers are described extensively in @ref{Debugging, ,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17257 Debugging Lisp Programs, elisp, The GNU Emacs Lisp Reference Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17258 In this chapter, I will walk through a short example of each.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17259
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17260 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17261 * debug:: How to use the built-in debugger.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17262 * debug-on-entry:: Start debugging when you call a function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17263 * debug-on-quit:: Start debugging when you quit with @kbd{C-g}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17264 * edebug:: How to use Edebug, a source level debugger.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17265 * Debugging Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17266 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17267
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17268 @node debug, debug-on-entry, Debugging, Debugging
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17269 @section @code{debug}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17270 @findex debug
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17271
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17272 Suppose you have written a function definition that is intended to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17273 return the sum of the numbers 1 through a given number. (This is the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17274 @code{triangle} function discussed earlier. @xref{Decrementing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17275 Example, , Example with Decrementing Counter}, for a discussion.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17276 @c xref{Decrementing Loop,, Loop with a Decrementing Counter}, for a discussion.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17277
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17278 However, your function definition has a bug. You have mistyped
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17279 @samp{1=} for @samp{1-}. Here is the broken definition:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17280
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17281 @findex triangle-bugged
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17282 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17283 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17284 (defun triangle-bugged (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17285 "Return sum of numbers 1 through NUMBER inclusive."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17286 (let ((total 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17287 (while (> number 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17288 (setq total (+ total number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17289 (setq number (1= number))) ; @r{Error here.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17290 total))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17291 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17292 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17293
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17294 If you are reading this in Info, you can evaluate this definition in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17295 the normal fashion. You will see @code{triangle-bugged} appear in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17296 echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17297
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17298 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17299 Now evaluate the @code{triangle-bugged} function with an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17300 argument of 4:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17301
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17302 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17303 (triangle-bugged 4)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17304 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17305
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17306 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17307 In GNU Emacs version 21, you will create and enter a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17308 @file{*Backtrace*} buffer that says:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17309
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17310 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17311 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17312 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17313 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17314 Debugger entered--Lisp error: (void-function 1=)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17315 (1= number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17316 (setq number (1= number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17317 (while (> number 0) (setq total (+ total number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17318 (setq number (1= number)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17319 (let ((total 0)) (while (> number 0) (setq total ...)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17320 (setq number ...)) total)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17321 triangle-bugged(4)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17322 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17323 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17324 eval((triangle-bugged 4))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17325 eval-last-sexp-1(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17326 eval-last-sexp(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17327 call-interactively(eval-last-sexp)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17328 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17329 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17330 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17331
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17332 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17333 (I have reformatted this example slightly; the debugger does not fold
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17334 long lines. As usual, you can quit the debugger by typing @kbd{q} in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17335 the @file{*Backtrace*} buffer.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17336
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17337 In practice, for a bug as simple as this, the `Lisp error' line will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17338 tell you what you need to know to correct the definition. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17339 function @code{1=} is `void'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17340
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17341 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17342 In GNU Emacs 20 and before, you will see:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17343
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17344 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17345 Symbol's function definition is void:@: 1=
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17346 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17347
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17348 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17349 which has the same meaning as the @file{*Backtrace*} buffer line in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17350 version 21.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17351
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17352 However, suppose you are not quite certain what is going on?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17353 You can read the complete backtrace.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17354
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17355 In this case, you need to run GNU Emacs 21, which automatically starts
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17356 the debugger that puts you in the @file{*Backtrace*} buffer; or else,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17357 you need to start the debugger manually as described below.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17358
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17359 Read the @file{*Backtrace*} buffer from the bottom up; it tells you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17360 what Emacs did that led to the error. Emacs made an interactive call
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17361 to @kbd{C-x C-e} (@code{eval-last-sexp}), which led to the evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17362 of the @code{triangle-bugged} expression. Each line above tells you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17363 what the Lisp interpreter evaluated next.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17364
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17365 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17366 The third line from the top of the buffer is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17367
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17368 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17369 (setq number (1= number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17370 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17371
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17372 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17373 Emacs tried to evaluate this expression; in order to do so, it tried
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17374 to evaluate the inner expression shown on the second line from the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17375 top:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17376
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17377 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17378 (1= number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17379 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17380
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17381 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17382 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17383 This is where the error occurred; as the top line says:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17384
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17385 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17386 Debugger entered--Lisp error: (void-function 1=)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17387 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17388
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17389 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17390 You can correct the mistake, re-evaluate the function definition, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17391 then run your test again.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17392
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17393 @node debug-on-entry, debug-on-quit, debug, Debugging
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17394 @section @code{debug-on-entry}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17395 @findex debug-on-entry
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17396
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17397 GNU Emacs 21 starts the debugger automatically when your function has
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17398 an error. GNU Emacs version 20 and before did not; it simply
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17399 presented you with an error message. You had to start the debugger
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17400 manually.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17401
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17402 You can start the debugger manually for all versions of Emacs; the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17403 advantage is that the debugger runs even if you do not have a bug in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17404 your code. Sometimes your code will be free of bugs!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17405
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17406 You can enter the debugger when you call the function by calling
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17407 @code{debug-on-entry}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17408
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17409 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17410 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17411 Type:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17412
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17413 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17414 M-x debug-on-entry RET triangle-bugged RET
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17415 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17416
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17417 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17418 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17419 Now, evaluate the following:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17420
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17421 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17422 (triangle-bugged 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17423 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17424
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17425 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17426 All versions of Emacs will create a @file{*Backtrace*} buffer and tell
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17427 you that it is beginning to evaluate the @code{triangle-bugged}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17428 function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17429
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17430 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17431 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17432 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17433 Debugger entered--entering a function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17434 * triangle-bugged(5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17435 eval((triangle-bugged 5))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17436 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17437 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17438 eval-last-sexp-1(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17439 eval-last-sexp(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17440 call-interactively(eval-last-sexp)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17441 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17442 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17443 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17444
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17445 In the @file{*Backtrace*} buffer, type @kbd{d}. Emacs will evaluate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17446 the first expression in @code{triangle-bugged}; the buffer will look
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17447 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17448
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17449 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17450 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17451 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17452 Debugger entered--beginning evaluation of function call form:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17453 * (let ((total 0)) (while (> number 0) (setq total ...)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17454 (setq number ...)) total)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17455 * triangle-bugged(5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17456 eval((triangle-bugged 5))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17457 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17458 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17459 eval-last-sexp-1(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17460 eval-last-sexp(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17461 call-interactively(eval-last-sexp)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17462 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17463 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17464 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17465
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17466 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17467 Now, type @kbd{d} again, eight times, slowly. Each time you type
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17468 @kbd{d}, Emacs will evaluate another expression in the function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17469 definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17470
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17471 @need 1750
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17472 Eventually, the buffer will look like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17473
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17474 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17475 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17476 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17477 Debugger entered--beginning evaluation of function call form:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17478 * (setq number (1= number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17479 * (while (> number 0) (setq total (+ total number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17480 (setq number (1= number)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17481 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17482 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17483 * (let ((total 0)) (while (> number 0) (setq total ...)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17484 (setq number ...)) total)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17485 * triangle-bugged(5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17486 eval((triangle-bugged 5))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17487 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17488 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17489 eval-last-sexp-1(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17490 eval-last-sexp(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17491 call-interactively(eval-last-sexp)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17492 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17493 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17494 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17495
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17496 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17497 Finally, after you type @kbd{d} two more times, Emacs will reach the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17498 error, and the top two lines of the @file{*Backtrace*} buffer will look
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17499 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17501 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17502 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17503 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17504 Debugger entered--Lisp error: (void-function 1=)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17505 * (1= number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17506 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17507 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17508 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17509 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17510
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17511 By typing @kbd{d}, you were able to step through the function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17512
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17513 You can quit a @file{*Backtrace*} buffer by typing @kbd{q} in it; this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17514 quits the trace, but does not cancel @code{debug-on-entry}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17515
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17516 @findex cancel-debug-on-entry
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17517 To cancel the effect of @code{debug-on-entry}, call
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17518 @code{cancel-debug-on-entry} and the name of the function, like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17519
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17520 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17521 M-x cancel-debug-on-entry RET triangle-bugged RET
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17522 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17523
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17524 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17525 (If you are reading this in Info, cancel @code{debug-on-entry} now.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17526
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17527 @node debug-on-quit, edebug, debug-on-entry, Debugging
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17528 @section @code{debug-on-quit} and @code{(debug)}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17529
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17530 In addition to setting @code{debug-on-error} or calling @code{debug-on-entry},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17531 there are two other ways to start @code{debug}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17532
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17533 @findex debug-on-quit
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17534 You can start @code{debug} whenever you type @kbd{C-g}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17535 (@code{keyboard-quit}) by setting the variable @code{debug-on-quit} to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17536 @code{t}. This is useful for debugging infinite loops.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17537
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17538 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17539 @cindex @code{(debug)} in code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17540 Or, you can insert a line that says @code{(debug)} into your code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17541 where you want the debugger to start, like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17542
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17543 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17544 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17545 (defun triangle-bugged (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17546 "Return sum of numbers 1 through NUMBER inclusive."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17547 (let ((total 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17548 (while (> number 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17549 (setq total (+ total number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17550 (debug) ; @r{Start debugger.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17551 (setq number (1= number))) ; @r{Error here.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17552 total))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17553 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17554 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17555
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17556 The @code{debug} function is described in detail in @ref{Debugger, ,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17557 The Lisp Debugger, elisp, The GNU Emacs Lisp Reference Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17558
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17559 @node edebug, Debugging Exercises, debug-on-quit, Debugging
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17560 @section The @code{edebug} Source Level Debugger
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17561 @cindex Source level debugger
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17562 @findex edebug
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17563
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17564 Edebug is a source level debugger. Edebug normally displays the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17565 source of the code you are debugging, with an arrow at the left that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17566 shows which line you are currently executing.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17567
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17568 You can walk through the execution of a function, line by line, or run
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17569 quickly until reaching a @dfn{breakpoint} where execution stops.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17570
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17571 Edebug is described in @ref{edebug, , Edebug, elisp, The GNU Emacs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17572 Lisp Reference Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17573
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17574 Here is a bugged function definition for @code{triangle-recursively}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17575 @xref{Recursive triangle function, , Recursion in place of a counter},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17576 for a review of it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17577
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17578 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17579 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17580 (defun triangle-recursively-bugged (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17581 "Return sum of numbers 1 through NUMBER inclusive.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17582 Uses recursion."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17583 (if (= number 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17584 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17585 (+ number
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17586 (triangle-recursively-bugged
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17587 (1= number))))) ; @r{Error here.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17588 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17589 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17590
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17591 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17592 Normally, you would install this definition by positioning your cursor
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17593 after the function's closing parenthesis and typing @kbd{C-x C-e}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17594 (@code{eval-last-sexp}) or else by positioning your cursor within the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17595 definition and typing @kbd{C-M-x} (@code{eval-defun}). (By default,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17596 the @code{eval-defun} command works only in Emacs Lisp mode or in Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17597 Interactive mode.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17598
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17599 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17600 However, to prepare this function definition for Edebug, you must
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17601 first @dfn{instrument} the code using a different command. You can do
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17602 this by positioning your cursor within the definition and typing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17603
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17604 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17605 M-x edebug-defun RET
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17606 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17607
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17608 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17609 This will cause Emacs to load Edebug automatically if it is not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17610 already loaded, and properly instrument the function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17611
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17612 After instrumenting the function, place your cursor after the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17613 following expression and type @kbd{C-x C-e} (@code{eval-last-sexp}):
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17614
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17615 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17616 (triangle-recursively-bugged 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17617 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17618
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17619 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17620 You will be jumped back to the source for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17621 @code{triangle-recursively-bugged} and the cursor positioned at the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17622 beginning of the @code{if} line of the function. Also, you will see
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17623 an arrowhead at the left hand side of that line. The arrowhead marks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17624 the line where the function is executing. (In the following examples,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17625 we show the arrowhead with @samp{=>}; in a windowing system, you may
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17626 see the arrowhead as a solid triangle in the window `fringe'.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17627
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17628 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17629 =>@point{}(if (= number 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17630 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17631
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17632 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17633 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17634 In the example, the location of point is displayed with a star,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17635 @samp{@point{}} (in Info, it is displayed as @samp{-!-}).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17636 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17637 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17638 In the example, the location of point is displayed as @samp{@point{}}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17639 (in a printed book, it is displayed with a five pointed star).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17640 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17641
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17642 If you now press @key{SPC}, point will move to the next expression to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17643 be executed; the line will look like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17644
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17645 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17646 =>(if @point{}(= number 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17647 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17648
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17649 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17650 As you continue to press @key{SPC}, point will move from expression to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17651 expression. At the same time, whenever an expression returns a value,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17652 that value will be displayed in the echo area. For example, after you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17653 move point past @code{number}, you will see the following:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17654
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17655 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17656 Result: 3 = C-c
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17657 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17658
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17659 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17660 This means the value of @code{number} is 3, which is @sc{ascii}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17661 `control-c' (the third letter of the alphabet).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17662
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17663 You can continue moving through the code until you reach the line with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17664 the error. Before evaluation, that line looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17665
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17666 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17667 => @point{}(1= number))))) ; @r{Error here.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17668 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17669
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17670 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17671 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17672 When you press @key{SPC} once again, you will produce an error message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17673 that says:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17674
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17675 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17676 Symbol's function definition is void:@: 1=
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17677 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17678
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17679 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17680 This is the bug.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17681
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17682 Press @kbd{q} to quit Edebug.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17683
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17684 To remove instrumentation from a function definition, simply
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17685 re-evaluate it with a command that does not instrument it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17686 For example, you could place your cursor after the definition's
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17687 closing parenthesis and type @kbd{C-x C-e}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17688
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17689 Edebug does a great deal more than walk with you through a function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17690 You can set it so it races through on its own, stopping only at an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17691 error or at specified stopping points; you can cause it to display the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17692 changing values of various expressions; you can find out how many
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17693 times a function is called, and more.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17694
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17695 Edebug is described in @ref{edebug, , Edebug, elisp, The GNU Emacs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17696 Lisp Reference Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17697
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17698 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17699 @node Debugging Exercises, , edebug, Debugging
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17700 @section Debugging Exercises
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17701
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17702 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17703 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17704 Install the @code{count-words-region} function and then cause it to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17705 enter the built-in debugger when you call it. Run the command on a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17706 region containing two words. You will need to press @kbd{d} a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17707 remarkable number of times. On your system, is a `hook' called after
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17708 the command finishes? (For information on hooks, see @ref{Command
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17709 Overview, , Command Loop Overview, elisp, The GNU Emacs Lisp Reference
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17710 Manual}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17711
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17712 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17713 Copy @code{count-words-region} into the @file{*scratch*} buffer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17714 instrument the function for Edebug, and walk through its execution.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17715 The function does not need to have a bug, although you can introduce
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17716 one if you wish. If the function lacks a bug, the walk-through
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17717 completes without problems.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17718
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17719 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17720 While running Edebug, type @kbd{?} to see a list of all the Edebug commands.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17721 (The @code{global-edebug-prefix} is usually @kbd{C-x X}, i.e.@:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17722 @kbd{@key{CTL}-x} followed by an upper case @kbd{X}; use this prefix
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17723 for commands made outside of the Edebug debugging buffer.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17724
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17725 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17726 In the Edebug debugging buffer, use the @kbd{p}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17727 (@code{edebug-bounce-point}) command to see where in the region the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17728 @code{count-words-region} is working.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17729
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17730 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17731 Move point to some spot further down function and then type the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17732 @kbd{h} (@code{edebug-goto-here}) command to jump to that location.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17733
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17734 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17735 Use the @kbd{t} (@code{edebug-trace-mode}) command to cause Edebug to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17736 walk through the function on its own; use an upper case @kbd{T} for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17737 @code{edebug-Trace-fast-mode}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17738
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17739 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17740 Set a breakpoint, then run Edebug in Trace mode until it reaches the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17741 stopping point.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17742 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17743
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17744 @node Conclusion, the-the, Debugging, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17745 @chapter Conclusion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17746
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17747 We have now reached the end of this Introduction. You have now
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17748 learned enough about programming in Emacs Lisp to set values, to write
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17749 simple @file{.emacs} files for yourself and your friends, and write
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17750 simple customizations and extensions to Emacs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17751
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17752 This is a place to stop. Or, if you wish, you can now go onward, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17753 teach yourself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17754
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17755 You have learned some of the basic nuts and bolts of programming. But
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17756 only some. There are a great many more brackets and hinges that are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17757 easy to use that we have not touched.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17758
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17759 A path you can follow right now lies among the sources to GNU Emacs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17760 and in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17761 @ifnotinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17762 @cite{The GNU Emacs Lisp Reference Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17763 @end ifnotinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17764 @ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17765 @ref{Top, , The GNU Emacs Lisp Reference Manual, elisp, The GNU
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17766 Emacs Lisp Reference Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17767 @end ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17768
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17769 The Emacs Lisp sources are an adventure. When you read the sources and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17770 come across a function or expression that is unfamiliar, you need to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17771 figure out or find out what it does.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17772
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17773 Go to the Reference Manual. It is a thorough, complete, and fairly
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17774 easy-to-read description of Emacs Lisp. It is written not only for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17775 experts, but for people who know what you know. (The @cite{Reference
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17776 Manual} comes with the standard GNU Emacs distribution. Like this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17777 introduction, it comes as a Texinfo source file, so you can read it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17778 on-line and as a typeset, printed book.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17779
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17780 Go to the other on-line help that is part of GNU Emacs: the on-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17781 documentation for all functions, and @code{find-tags}, the program
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17782 that takes you to sources.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17783
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17784 Here is an example of how I explore the sources. Because of its name,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17785 @file{simple.el} is the file I looked at first, a long time ago. As
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17786 it happens some of the functions in @file{simple.el} are complicated,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17787 or at least look complicated at first sight. The @code{open-line}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17788 function, for example, looks complicated.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17789
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17790 You may want to walk through this function slowly, as we did with the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17791 @code{forward-sentence} function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17792 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17793 (@xref{forward-sentence}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17794 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17795 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17796 (@xref{forward-sentence, , @code{forward-sentence}}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17797 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17798 Or you may want to skip that function and look at another, such as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17799 @code{split-line}. You don't need to read all the functions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17800 According to @code{count-words-in-defun}, the @code{split-line}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17801 function contains 27 words and symbols.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17802
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17803 Even though it is short, @code{split-line} contains four expressions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17804 we have not studied: @code{skip-chars-forward}, @code{indent-to},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17805 @code{current-column} and @samp{?\n}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17806
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17807 Consider the @code{skip-chars-forward} function. (It is part of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17808 function definition for @code{back-to-indentation}, which is shown in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17809 @ref{Review, , Review}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17810
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17811 In GNU Emacs, you can find out more about @code{skip-chars-forward} by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17812 typing @kbd{C-h f} (@code{describe-function}) and the name of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17813 function. This gives you the function documentation.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17814
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17815 You may be able to guess what is done by a well named function such as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17816 @code{indent-to}; or you can look it up, too. Incidentally, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17817 @code{describe-function} function itself is in @file{help.el}; it is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17818 one of those long, but decipherable functions. You can look up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17819 @code{describe-function} using the @kbd{C-h f} command!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17820
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17821 In this instance, since the code is Lisp, the @file{*Help*} buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17822 contains the name of the library containing the function's source.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17823 You can put point over the name of the library and press the RET key,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17824 which in this situation is bound to @code{help-follow}, and be taken
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17825 directly to the source, in the same way as @kbd{M-.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17826 (@code{find-tag}).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17827
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17828 The definition for @code{describe-function} illustrates how to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17829 customize the @code{interactive} expression without using the standard
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17830 character codes; and it shows how to create a temporary buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17831
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17832 (The @code{indent-to} function is written in C rather than Emacs Lisp;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17833 it is a `built-in' function. @code{help-follow} only provides you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17834 with the documentation of a built-in function; it does not take you to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17835 the source. But @code{find-tag} will take you to the source, if
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17836 properly set up.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17837
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17838 You can look at a function's source using @code{find-tag}, which is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17839 bound to @kbd{M-.} Finally, you can find out what the Reference
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17840 Manual has to say by visiting the manual in Info, and typing @kbd{i}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17841 (@code{Info-index}) and the name of the function, or by looking up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17842 @code{skip-chars-forward} in the index to a printed copy of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17843 manual.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17844
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17845 Similarly, you can find out what is meant by @samp{?\n}. You can try
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17846 using @code{Info-index} with @samp{?\n}. It turns out that this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17847 action won't help; but don't give up. If you search the index for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17848 @samp{\n} without the @samp{?}, you will be taken directly to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17849 relevant section of the manual. (@xref{Character Type, , Character
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17850 Type, elisp, The GNU Emacs Lisp Reference Manual}. @samp{?\n} stands
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17851 for the newline character.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17852
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17853 Other interesting source files include @file{paragraphs.el},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17854 @file{loaddefs.el}, and @file{loadup.el}. The @file{paragraphs.el}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17855 file includes short, easily understood functions as well as longer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17856 ones. The @file{loaddefs.el} file contains the many standard
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17857 autoloads and many keymaps. I have never looked at it all; only at
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17858 parts. @file{loadup.el} is the file that loads the standard parts of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17859 Emacs; it tells you a great deal about how Emacs is built.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17860 (@xref{Building Emacs, , Building Emacs, elisp, The GNU Emacs Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17861 Reference Manual}, for more about building.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17862
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17863 As I said, you have learned some nuts and bolts; however, and very
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17864 importantly, we have hardly touched major aspects of programming; I
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17865 have said nothing about how to sort information, except to use the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17866 predefined @code{sort} function; I have said nothing about how to store
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17867 information, except to use variables and lists; I have said nothing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17868 about how to write programs that write programs. These are topics for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17869 another, and different kind of book, a different kind of learning.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17870
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17871 What you have done is learn enough for much practical work with GNU
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17872 Emacs. What you have done is get started. This is the end of a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17873 beginning.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17874
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17875 @c ================ Appendix ================
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17876
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17877 @node the-the, Kill Ring, Conclusion, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17878 @appendix The @code{the-the} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17879 @findex the-the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17880 @cindex Duplicated words function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17881 @cindex Words, duplicated
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17882
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17883 Sometimes when you you write text, you duplicate words---as with ``you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17884 you'' near the beginning of this sentence. I find that most
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17885 frequently, I duplicate ``the'; hence, I call the function for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17886 detecting duplicated words, @code{the-the}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17887
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17888 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17889 As a first step, you could use the following regular expression to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17890 search for duplicates:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17891
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17892 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17893 \\(\\w+[ \t\n]+\\)\\1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17894 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17895
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17896 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17897 This regexp matches one or more word-constituent characters followed
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17898 by one or more spaces, tabs, or newlines. However, it does not detect
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17899 duplicated words on different lines, since the ending of the first
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17900 word, the end of the line, is different from the ending of the second
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17901 word, a space. (For more information about regular expressions, see
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17902 @ref{Regexp Search, , Regular Expression Searches}, as well as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17903 @ref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17904 Manual}, and @ref{Regular Expressions, , Regular Expressions, elisp,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17905 The GNU Emacs Lisp Reference Manual}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17906
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17907 You might try searching just for duplicated word-constituent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17908 characters but that does not work since the pattern detects doubles
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17909 such as the two occurrences of `th' in `with the'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17910
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17911 Another possible regexp searches for word-constituent characters
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17912 followed by non-word-constituent characters, reduplicated. Here,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17913 @w{@samp{\\w+}} matches one or more word-constituent characters and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17914 @w{@samp{\\W*}} matches zero or more non-word-constituent characters.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17915
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17916 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17917 \\(\\(\\w+\\)\\W*\\)\\1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17918 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17919
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17920 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17921 Again, not useful.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17922
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17923 Here is the pattern that I use. It is not perfect, but good enough.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17924 @w{@samp{\\b}} matches the empty string, provided it is at the beginning
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17925 or end of a word; @w{@samp{[^@@ \n\t]+}} matches one or more occurrences of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17926 any characters that are @emph{not} an @@-sign, space, newline, or tab.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17927
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17928 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17929 \\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17930 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17931
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17932 One can write more complicated expressions, but I found that this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17933 expression is good enough, so I use it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17934
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17935 Here is the @code{the-the} function, as I include it in my
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17936 @file{.emacs} file, along with a handy global key binding:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17937
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17938 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17939 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17940 (defun the-the ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17941 "Search forward for for a duplicated word."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17942 (interactive)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17943 (message "Searching for for duplicated words ...")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17944 (push-mark)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17945 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17946 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17947 ;; This regexp is not perfect
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17948 ;; but is fairly good over all:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17949 (if (re-search-forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17950 "\\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b" nil 'move)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17951 (message "Found duplicated word.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17952 (message "End of buffer")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17953 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17954
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17955 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17956 ;; Bind `the-the' to C-c \
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17957 (global-set-key "\C-c\\" 'the-the)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17958 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17959 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17960
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17961 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17962 Here is test text:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17963
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17964 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17965 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17966 one two two three four five
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17967 five six seven
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17968 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17969 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17970
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17971 You can substitute the other regular expressions shown above in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17972 function definition and try each of them on this list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17973
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17974 @node Kill Ring, Full Graph, the-the, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17975 @appendix Handling the Kill Ring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17976 @cindex Kill ring handling
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17977 @cindex Handling the kill ring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17978 @cindex Ring, making a list like a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17979
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17980 The kill ring is a list that is transformed into a ring by the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17981 workings of the @code{rotate-yank-pointer} function. The @code{yank}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17982 and @code{yank-pop} commands use the @code{rotate-yank-pointer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17983 function. This appendix describes the @code{rotate-yank-pointer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17984 function as well as both the @code{yank} and the @code{yank-pop}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17985 commands.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17986
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17987 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17988 * rotate-yank-pointer:: Move a pointer along a list and around.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17989 * yank:: Paste a copy of a clipped element.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17990 * yank-pop:: Insert first element pointed to.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17991 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17992
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17993 @node rotate-yank-pointer, yank, Kill Ring, Kill Ring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17994 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17995 @appendixsec The @code{rotate-yank-pointer} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17996 @findex rotate-yank-pointer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17997
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17998 The @code{rotate-yank-pointer} function changes the element in the kill
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17999 ring to which @code{kill-ring-yank-pointer} points. For example, it can
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18000 change @code{kill-ring-yank-pointer} from pointing to the second
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18001 element to point to the third element.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18002
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18003 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18004 Here is the code for @code{rotate-yank-pointer}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18005
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18006 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18007 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18008 (defun rotate-yank-pointer (arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18009 "Rotate the yanking point in the kill ring."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18010 (interactive "p")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18011 (let ((length (length kill-ring)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18012 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18013 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18014 (if (zerop length)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18015 ;; @r{then-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18016 (error "Kill ring is empty")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18017 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18018 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18019 ;; @r{else-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18020 (setq kill-ring-yank-pointer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18021 (nthcdr (% (+ arg
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18022 (- length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18023 (length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18024 kill-ring-yank-pointer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18025 length)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18026 kill-ring)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18027 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18028 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18029
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18030 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18031 * Understanding rotate-yk-ptr::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18032 * rotate-yk-ptr body:: The body of @code{rotate-yank-pointer}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18033 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18034
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18035 @node Understanding rotate-yk-ptr, rotate-yk-ptr body, rotate-yank-pointer, rotate-yank-pointer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18036 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18037 @unnumberedsubsec @code{rotate-yank-pointer} in Outline
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18038 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18039
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18040 The @code{rotate-yank-pointer} function looks complex, but as usual,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18041 it can be understood by taking it apart piece by piece. First look at
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18042 it in skeletal form:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18043
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18044 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18045 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18046 (defun rotate-yank-pointer (arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18047 "Rotate the yanking point in the kill ring."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18048 (interactive "p")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18049 (let @var{varlist}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18050 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18051 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18052 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18053
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18054 This function takes one argument, called @code{arg}. It has a brief
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18055 documentation string; and it is interactive with a small @samp{p}, which
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18056 means that the argument must be a processed prefix passed to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18057 function as a number.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18058
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18059 The body of the function definition is a @code{let} expression, which
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18060 itself has a body as well as a @var{varlist}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18061
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18062 The @code{let} expression declares a variable that will be only usable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18063 within the bounds of this function. This variable is called
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18064 @code{length} and is bound to a value that is equal to the number of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18065 items in the kill ring. This is done by using the function called
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18066 @code{length}. (Note that this function has the same name as the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18067 variable called @code{length}; but one use of the word is to name the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18068 function and the other is to name the variable. The two are quite
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18069 distinct. Similarly, an English speaker will distinguish between the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18070 meanings of the word @samp{ship} when he says: "I must ship this package
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18071 immediately." and "I must get aboard the ship immediately.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18072
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18073 The function @code{length} tells the number of items there are in a list,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18074 so @code{(length kill-ring)} returns the number of items there are in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18075 kill ring.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18076
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18077 @node rotate-yk-ptr body, , Understanding rotate-yk-ptr, rotate-yank-pointer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18078 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18079 @appendixsubsec The Body of @code{rotate-yank-pointer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18080
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18081 The body of @code{rotate-yank-pointer} is a @code{let} expression and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18082 the body of the @code{let} expression is an @code{if} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18083
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18084 The purpose of the @code{if} expression is to find out whether there is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18085 anything in the kill ring. If the kill ring is empty, the @code{error}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18086 function stops evaluation of the function and prints a message in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18087 echo area. On the other hand, if the kill ring has something in it, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18088 work of the function is done.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18089
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18090 Here is the if-part and then-part of the @code{if} expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18091
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18092 @findex zerop
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18093 @findex error
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18094 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18095 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18096 (if (zerop length) ; @r{if-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18097 (error "Kill ring is empty") ; @r{then-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18098 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18099 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18100 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18101
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18102 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18103 If there is not anything in the kill ring, its length must be zero and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18104 an error message sent to the user: @samp{Kill ring is empty}. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18105 @code{if} expression uses the function @code{zerop} which returns true
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18106 if the value it is testing is zero. When @code{zerop} tests true, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18107 then-part of the @code{if} is evaluated. The then-part is a list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18108 starting with the function @code{error}, which is a function that is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18109 similar to the @code{message} function (@pxref{message}), in that it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18110 prints a one-line message in the echo area. However, in addition to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18111 printing a message, @code{error} also stops evaluation of the function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18112 within which it is embedded. This means that the rest of the function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18113 will not be evaluated if the length of the kill ring is zero.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18114
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18115 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18116 * Digression concerning error:: How to mislead humans, but not computers.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18117 * rotate-yk-ptr else-part:: The else-part of the @code{if} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18118 * Remainder Function:: The remainder, @code{%}, function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18119 * rotate-yk-ptr remainder:: Using @code{%} in @code{rotate-yank-pointer}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18120 * kill-rng-yk-ptr last elt:: Pointing to the last element.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18121 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18122
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18123 @node Digression concerning error, rotate-yk-ptr else-part, rotate-yk-ptr body, rotate-yk-ptr body
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18124 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18125 @unnumberedsubsubsec Digression about the word `error'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18126 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18127
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18128 (In my opinion, it is slightly misleading, at least to humans, to use
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18129 the term `error' as the name of the @code{error} function. A better
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18130 term would be `cancel'. Strictly speaking, of course, you cannot
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18131 point to, much less rotate a pointer to a list that has no length, so
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18132 from the point of view of the computer, the word `error' is correct.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18133 But a human expects to attempt this sort of thing, if only to find out
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18134 whether the kill ring is full or empty. This is an act of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18135 exploration.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18136
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18137 (From the human point of view, the act of exploration and discovery is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18138 not necessarily an error, and therefore should not be labelled as one,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18139 even in the bowels of a computer. As it is, the code in Emacs implies
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18140 that a human who is acting virtuously, by exploring his or her
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18141 environment, is making an error. This is bad. Even though the computer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18142 takes the same steps as it does when there is an `error', a term such as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18143 `cancel' would have a clearer connotation.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18144
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18145 @node rotate-yk-ptr else-part, Remainder Function, Digression concerning error, rotate-yk-ptr body
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18146 @unnumberedsubsubsec The else-part of the @code{if} expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18147
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18148 The else-part of the @code{if} expression is dedicated to setting the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18149 value of @code{kill-ring-yank-pointer} when the kill ring has something
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18150 in it. The code looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18151
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18152 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18153 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18154 (setq kill-ring-yank-pointer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18155 (nthcdr (% (+ arg
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18156 (- length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18157 (length kill-ring-yank-pointer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18158 length)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18159 kill-ring)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18160 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18161 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18162
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18163 This needs some examination. Clearly, @code{kill-ring-yank-pointer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18164 is being set to be equal to some @sc{cdr} of the kill ring, using the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18165 @code{nthcdr} function that is described in an earlier section.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18166 (@xref{copy-region-as-kill}.) But exactly how does it do this?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18167
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18168 Before looking at the details of the code let's first consider the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18169 purpose of the @code{rotate-yank-pointer} function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18170
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18171 The @code{rotate-yank-pointer} function changes what
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18172 @code{kill-ring-yank-pointer} points to. If
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18173 @code{kill-ring-yank-pointer} starts by pointing to the first element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18174 of a list, a call to @code{rotate-yank-pointer} causes it to point to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18175 the second element; and if @code{kill-ring-yank-pointer} points to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18176 second element, a call to @code{rotate-yank-pointer} causes it to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18177 point to the third element. (And if @code{rotate-yank-pointer} is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18178 given an argument greater than 1, it jumps the pointer that many
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18179 elements.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18180
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18181 The @code{rotate-yank-pointer} function uses @code{setq} to reset what
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18182 the @code{kill-ring-yank-pointer} points to. If
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18183 @code{kill-ring-yank-pointer} points to the first element of the kill
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18184 ring, then, in the simplest case, the @code{rotate-yank-pointer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18185 function must cause it to point to the second element. Put another
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18186 way, @code{kill-ring-yank-pointer} must be reset to have a value equal
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18187 to the @sc{cdr} of the kill ring.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18188
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18189 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18190 That is, under these circumstances,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18191
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18192 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18193 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18194 (setq kill-ring-yank-pointer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18195 ("some text" "a different piece of text" "yet more text"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18196
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18197 (setq kill-ring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18198 ("some text" "a different piece of text" "yet more text"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18199 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18200 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18201
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18202 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18203 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18204 the code should do this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18205
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18206 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18207 (setq kill-ring-yank-pointer (cdr kill-ring))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18208 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18209
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18210 @need 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18211 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18212 As a result, the @code{kill-ring-yank-pointer} will look like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18213
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18214 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18215 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18216 kill-ring-yank-pointer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18217 @result{} ("a different piece of text" "yet more text"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18218 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18219 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18220
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18221 The actual @code{setq} expression uses the @code{nthcdr} function to do
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18222 the job.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18223
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18224 As we have seen before (@pxref{nthcdr}), the @code{nthcdr} function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18225 works by repeatedly taking the @sc{cdr} of a list---it takes the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18226 @sc{cdr} of the @sc{cdr} of the @sc{cdr} @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18227
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18228 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18229 The two following expressions produce the same result:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18230
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18231 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18232 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18233 (setq kill-ring-yank-pointer (cdr kill-ring))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18234
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18235 (setq kill-ring-yank-pointer (nthcdr 1 kill-ring))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18236 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18237 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18238
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18239 In the @code{rotate-yank-pointer} function, however, the first
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18240 argument to @code{nthcdr} is a rather complex looking expression with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18241 lots of arithmetic inside of it:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18242
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18243 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18244 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18245 (% (+ arg
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18246 (- length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18247 (length kill-ring-yank-pointer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18248 length)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18249 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18250 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18251
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18252 As usual, we need to look at the most deeply embedded expression first
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18253 and then work our way towards the light.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18254
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18255 The most deeply embedded expression is @code{(length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18256 kill-ring-yank-pointer)}. This finds the length of the current value of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18257 the @code{kill-ring-yank-pointer}. (Remember that the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18258 @code{kill-ring-yank-pointer} is the name of a variable whose value is a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18259 list.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18260
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18261 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18262 The measurement of the length is inside the expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18263
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18264 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18265 (- length (length kill-ring-yank-pointer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18266 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18267
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18268 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18269 In this expression, the first @code{length} is the variable that was
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18270 assigned the length of the kill ring in the @code{let} statement at the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18271 beginning of the function. (One might think this function would be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18272 clearer if the variable @code{length} were named
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18273 @code{length-of-kill-ring} instead; but if you look at the text of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18274 whole function, you will see that it is so short that naming this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18275 variable @code{length} is not a bother, unless you are pulling the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18276 function apart into very tiny pieces as we are doing here.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18277
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18278 So the line @code{(- length (length kill-ring-yank-pointer))} tells the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18279 difference between the length of the kill ring and the length of the list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18280 whose name is @code{kill-ring-yank-pointer}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18281
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18282 To see how all this fits into the @code{rotate-yank-pointer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18283 function, let's begin by analyzing the case where
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18284 @code{kill-ring-yank-pointer} points to the first element of the kill
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18285 ring, just as @code{kill-ring} does, and see what happens when
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18286 @code{rotate-yank-pointer} is called with an argument of 1.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18287
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18288 The variable @code{length} and the value of the expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18289 @code{(length kill-ring-yank-pointer)} will be the same since the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18290 variable @code{length} is the length of the kill ring and the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18291 @code{kill-ring-yank-pointer} is pointing to the whole kill ring.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18292 Consequently, the value of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18293
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18294 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18295 (- length (length kill-ring-yank-pointer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18296 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18297
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18298 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18299 will be zero. Since the value of @code{arg} will be 1, this will mean
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18300 that the value of the whole expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18301
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18302 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18303 (+ arg (- length (length kill-ring-yank-pointer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18304 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18305
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18306 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18307 will be 1.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18308
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18309 Consequently, the argument to @code{nthcdr} will be found as the result of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18310 the expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18311
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18312 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18313 (% 1 length)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18314 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18315
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18316 @node Remainder Function, rotate-yk-ptr remainder, rotate-yk-ptr else-part, rotate-yk-ptr body
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18317 @unnumberedsubsubsec The @code{%} remainder function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18318
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18319 To understand @code{(% 1 length)}, we need to understand @code{%}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18320 According to its documentation (which I just found by typing @kbd{C-h
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18321 f @kbd{%} @key{RET}}), the @code{%} function returns the remainder of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18322 its first argument divided by its second argument. For example, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18323 remainder of 5 divided by 2 is 1. (2 goes into 5 twice with a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18324 remainder of 1.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18325
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18326 What surprises people who don't often do arithmetic is that a smaller
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18327 number can be divided by a larger number and have a remainder. In the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18328 example we just used, 5 was divided by 2. We can reverse that and ask,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18329 what is the result of dividing 2 by 5? If you can use fractions, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18330 answer is obviously 2/5 or .4; but if, as here, you can only use whole
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18331 numbers, the result has to be something different. Clearly, 5 can go into
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18332 2 zero times, but what of the remainder? To see what the answer is,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18333 consider a case that has to be familiar from childhood:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18334
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18335 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18336 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18337 5 divided by 5 is 1 with a remainder of 0;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18338
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18339 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18340 6 divided by 5 is 1 with a remainder of 1;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18341
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18342 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18343 7 divided by 5 is 1 with a remainder of 2.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18344
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18345 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18346 Similarly, 10 divided by 5 is 2 with a remainder of 0;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18347
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18348 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18349 11 divided by 5 is 2 with a remainder of 1;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18350
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18351 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18352 12 divided by 5 is 1 with a remainder of 2.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18353 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18354
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18355 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18356 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18357 By considering the cases as parallel, we can see that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18358
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18359 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18360 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18361 zero divided by 5 must be zero with a remainder of zero;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18362
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18363 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18364 1 divided by 5 must be zero with a remainder of 1;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18365
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18366 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18367 2 divided by 5 must be zero with a remainder of 2;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18368 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18369
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18370 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18371 and so on.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18372
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18373 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18374 So, in this code, if the value of @code{length} is 5, then the result of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18375 evaluating
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18376
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18377 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18378 (% 1 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18379 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18380
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18381 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18382 is 1. (I just checked this by placing the cursor after the expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18383 and typing @kbd{C-x C-e}. Indeed, 1 is printed in the echo area.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18384
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18385 @node rotate-yk-ptr remainder, kill-rng-yk-ptr last elt, Remainder Function, rotate-yk-ptr body
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18386 @unnumberedsubsubsec Using @code{%} in @code{rotate-yank-pointer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18387
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18388 When the @code{kill-ring-yank-pointer} points to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18389 beginning of the kill ring, and the argument passed to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18390 @code{rotate-yank-pointer} is 1, the @code{%} expression returns 1:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18391
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18392 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18393 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18394 (- length (length kill-ring-yank-pointer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18395 @result{} 0
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18396 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18397 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18398
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18399 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18400 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18401 therefore,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18402
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18403 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18404 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18405 (+ arg (- length (length kill-ring-yank-pointer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18406 @result{} 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18407 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18408 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18409
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18410 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18411 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18412 and consequently:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18413
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18414 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18415 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18416 (% (+ arg (- length (length kill-ring-yank-pointer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18417 length)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18418 @result{} 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18419 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18420 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18422 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18423 regardless of the value of @code{length}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18424
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18425 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18426 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18427 As a result of this, the @code{setq kill-ring-yank-pointer} expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18428 simplifies to:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18429
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18430 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18431 (setq kill-ring-yank-pointer (nthcdr 1 kill-ring))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18432 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18433
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18434 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18435 What it does is now easy to understand. Instead of pointing as it did
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18436 to the first element of the kill ring, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18437 @code{kill-ring-yank-pointer} is set to point to the second element.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18438
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18439 Clearly, if the argument passed to @code{rotate-yank-pointer} is two, then
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18440 the @code{kill-ring-yank-pointer} is set to @code{(nthcdr 2 kill-ring)};
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18441 and so on for different values of the argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18442
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18443 Similarly, if the @code{kill-ring-yank-pointer} starts out pointing to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18444 the second element of the kill ring, its length is shorter than the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18445 length of the kill ring by 1, so the computation of the remainder is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18446 based on the expression @code{(% (+ arg 1) length)}. This means that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18447 the @code{kill-ring-yank-pointer} is moved from the second element of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18448 the kill ring to the third element if the argument passed to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18449 @code{rotate-yank-pointer} is 1.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18450
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18451 @node kill-rng-yk-ptr last elt, , rotate-yk-ptr remainder, rotate-yk-ptr body
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18452 @unnumberedsubsubsec Pointing to the last element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18453
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18454 The final question is, what happens if the @code{kill-ring-yank-pointer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18455 is set to the @emph{last} element of the kill ring? Will a call to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18456 @code{rotate-yank-pointer} mean that nothing more can be taken from the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18457 kill ring? The answer is no. What happens is different and useful.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18458 The @code{kill-ring-yank-pointer} is set to point to the beginning of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18459 the kill ring instead.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18460
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18461 Let's see how this works by looking at the code, assuming the length of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18462 kill ring is 5 and the argument passed to @code{rotate-yank-pointer} is 1.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18463 When the @code{kill-ring-yank-pointer} points to the last element of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18464 the kill ring, its length is 1. The code looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18465
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18466 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18467 (% (+ arg (- length (length kill-ring-yank-pointer))) length)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18468 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18469
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18470 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18471 When the variables are replaced by their numeric values, the expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18472 looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18473
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18474 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18475 (% (+ 1 (- 5 1)) 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18476 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18477
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18478 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18479 This expression can be evaluated by looking at the most embedded inner
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18480 expression first and working outwards: The value of @code{(- 5 1)} is 4;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18481 the sum of @code{(+ 1 4)} is 5; and the remainder of dividing 5 by 5 is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18482 zero. So what @code{rotate-yank-pointer} will do is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18483
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18484 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18485 (setq kill-ring-yank-pointer (nthcdr 0 kill-ring))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18486 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18487
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18488 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18489 which will set the @code{kill-ring-yank-pointer} to point to the beginning
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18490 of the kill ring.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18491
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18492 So what happens with successive calls to @code{rotate-yank-pointer} is that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18493 it moves the @code{kill-ring-yank-pointer} from element to element in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18494 kill ring until it reaches the end; then it jumps back to the beginning.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18495 And this is why the kill ring is called a ring, since by jumping back to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18496 the beginning, it is as if the list has no end! (And what is a ring, but
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18497 an entity with no end?)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18498
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18499 @node yank, yank-pop, rotate-yank-pointer, Kill Ring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18500 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18501 @appendixsec @code{yank}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18502 @findex yank
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18503
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18504 After learning about @code{rotate-yank-pointer}, the code for the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18505 @code{yank} function is almost easy. It has only one tricky part, which is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18506 the computation of the argument to be passed to @code{rotate-yank-pointer}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18507
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18508 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18509 The code looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18510
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18511 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18512 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18513 (defun yank (&optional arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18514 "Reinsert the last stretch of killed text.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18515 More precisely, reinsert the stretch of killed text most
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18516 recently killed OR yanked.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18517 With just C-U as argument, same but put point in front
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18518 (and mark at end). With argument n, reinsert the nth
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18519 most recently killed stretch of killed text.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18520 See also the command \\[yank-pop]."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18521 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18522 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18523
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18524 (interactive "*P")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18525 (rotate-yank-pointer (if (listp arg) 0
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18526 (if (eq arg '-) -1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18527 (1- arg))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18528 (push-mark (point))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18529 (insert (car kill-ring-yank-pointer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18530 (if (consp arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18531 (exchange-point-and-mark)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18532 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18533 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18534
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18535 Glancing over this code, we can understand the last few lines readily
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18536 enough. The mark is pushed, that is, remembered; then the first element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18537 (the @sc{car}) of what the @code{kill-ring-yank-pointer} points to is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18538 inserted; and then, if the argument passed the function is a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18539 @code{cons}, point and mark are exchanged so the point is put in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18540 front of the inserted text rather than at the end. This option is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18541 explained in the documentation. The function itself is interactive with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18542 @code{"*P"}. This means it will not work on a read-only buffer, and that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18543 the unprocessed prefix argument is passed to the function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18544
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18545 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18546 * rotate-yk-ptr arg:: Pass the argument to @code{rotate-yank-pointer}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18547 * rotate-yk-ptr negative arg:: Pass a negative argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18548 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18549
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18550 @node rotate-yk-ptr arg, rotate-yk-ptr negative arg, yank, yank
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18551 @unnumberedsubsubsec Passing the argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18552
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18553 The hard part of @code{yank} is understanding the computation that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18554 determines the value of the argument passed to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18555 @code{rotate-yank-pointer}. Fortunately, it is not so difficult as it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18556 looks at first sight.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18557
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18558 What happens is that the result of evaluating one or both of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18559 @code{if} expressions will be a number and that number will be the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18560 argument passed to @code{rotate-yank-pointer}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18561
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18562 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18563 Laid out with comments, the code looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18564
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18565 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18566 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18567 (if (listp arg) ; @r{if-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18568 0 ; @r{then-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18569 (if (eq arg '-) ; @r{else-part, inner if}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18570 -1 ; @r{inner if's then-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18571 (1- arg)))) ; @r{inner if's else-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18572 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18573 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18574
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18575 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18576 This code consists of two @code{if} expression, one the else-part of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18577 the other.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18578
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18579 The first or outer @code{if} expression tests whether the argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18580 passed to @code{yank} is a list. Oddly enough, this will be true if
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18581 @code{yank} is called without an argument---because then it will be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18582 passed the value of @code{nil} for the optional argument and an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18583 evaluation of @code{(listp nil)} returns true! So, if no argument is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18584 passed to @code{yank}, the argument passed to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18585 @code{rotate-yank-pointer} inside of @code{yank} is zero. This means
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18586 the pointer is not moved and the first element to which
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18587 @code{kill-ring-yank-pointer} points is inserted, as we expect.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18588 Similarly, if the argument for @code{yank} is @kbd{C-u}, this will be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18589 read as a list, so again, a zero will be passed to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18590 @code{rotate-yank-pointer}. (@kbd{C-u} produces an unprocessed prefix
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18591 argument of @code{(4)}, which is a list of one element.) At the same
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18592 time, later in the function, this argument will be read as a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18593 @code{cons} so point will be put in the front and mark at the end of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18594 the insertion. (The @code{P} argument to @code{interactive} is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18595 designed to provide these values for the case when an optional
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18596 argument is not provided or when it is @kbd{C-u}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18597
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18598 The then-part of the outer @code{if} expression handles the case when
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18599 there is no argument or when it is @kbd{C-u}. The else-part handles the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18600 other situations. The else-part is itself another @code{if} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18601
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18602 The inner @code{if} expression tests whether the argument is a minus
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18603 sign. (This is done by pressing the @key{META} and @kbd{-} keys at the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18604 same time, or the @key{ESC} key and then the @kbd{-} key). In this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18605 case, the @code{rotate-yank-pointer} function is passed @kbd{-1} as an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18606 argument. This moves the @code{kill-ring-yank-pointer} backwards, which
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18607 is what is desired.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18608
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18609 If the true-or-false-test of the inner @code{if} expression is false
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18610 (that is, if the argument is not a minus sign), the else-part of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18611 expression is evaluated. This is the expression @code{(1- arg)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18612 Because of the two @code{if} expressions, it will only occur when the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18613 argument is a positive number or when it is a negative number (not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18614 just a minus sign on its own). What @code{(1- arg)} does is decrement
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18615 the number and return it. (The @code{1-} function subtracts one from
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18616 its argument.) This means that if the argument to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18617 @code{rotate-yank-pointer} is 1, it is reduced to zero, which means
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18618 the first element to which @code{kill-ring-yank-pointer} points is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18619 yanked back, as you would expect.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18620
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18621 @node rotate-yk-ptr negative arg, , rotate-yk-ptr arg, yank
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18622 @unnumberedsubsubsec Passing a negative argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18623
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18624 Finally, the question arises, what happens if either the remainder
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18625 function, @code{%}, or the @code{nthcdr} function is passed a negative
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18626 argument, as they quite well may?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18627
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18628 The answers can be found by a quick test. When @code{(% -1 5)} is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18629 evaluated, a negative number is returned; and if @code{nthcdr} is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18630 called with a negative number, it returns the same value as if it were
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18631 called with a first argument of zero. This can be seen be evaluating
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18632 the following code.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18633
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18634 Here the @samp{@result{}} points to the result of evaluating the code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18635 preceding it. This was done by positioning the cursor after the code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18636 and typing @kbd{C-x C-e} (@code{eval-last-sexp}) in the usual fashion.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18637 You can do this if you are reading this in Info inside of GNU Emacs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18638
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18639 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18640 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18641 (% -1 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18642 @result{} -1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18643 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18644
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18645 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18646 (setq animals '(cats dogs elephants))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18647 @result{} (cats dogs elephants)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18648 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18649
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18650 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18651 (nthcdr 1 animals)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18652 @result{} (dogs elephants)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18653 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18654
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18655 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18656 (nthcdr 0 animals)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18657 @result{} (cats dogs elephants)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18658 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18659
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18660 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18661 (nthcdr -1 animals)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18662 @result{} (cats dogs elephants)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18663 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18664 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18665
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18666 So, if a minus sign or a negative number is passed to @code{yank}, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18667 @code{kill-ring-yank-point} is rotated backwards until it reaches the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18668 beginning of the list. Then it stays there. Unlike the other case,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18669 when it jumps from the end of the list to the beginning of the list,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18670 making a ring, it stops. This makes sense. You often want to get back
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18671 to the most recently clipped out piece of text, but you don't usually
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18672 want to insert text from as many as thirty kill commands ago. So you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18673 need to work through the ring to get to the end, but won't cycle around
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18674 it inadvertently if you are trying to come back to the beginning.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18675
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18676 Incidentally, any number passed to @code{yank} with a minus sign
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18677 preceding it will be treated as @minus{}1. This is evidently a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18678 simplification for writing the program. You don't need to jump back
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18679 towards the beginning of the kill ring more than one place at a time
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18680 and doing this is easier than writing a function to determine the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18681 magnitude of the number that follows the minus sign.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18682
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18683 @node yank-pop, , yank, Kill Ring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18684 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18685 @appendixsec @code{yank-pop}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18686 @findex yank-pop
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18687
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18688 After understanding @code{yank}, the @code{yank-pop} function is easy.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18689 Leaving out the documentation to save space, it looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18690
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18691 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18692 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18693 (defun yank-pop (arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18694 (interactive "*p")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18695 (if (not (eq last-command 'yank))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18696 (error "Previous command was not a yank"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18697 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18698 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18699 (setq this-command 'yank)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18700 (let ((before (< (point) (mark))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18701 (delete-region (point) (mark))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18702 (rotate-yank-pointer arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18703 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18704 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18705 (set-mark (point))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18706 (insert (car kill-ring-yank-pointer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18707 (if before (exchange-point-and-mark))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18708 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18709 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18710
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18711 The function is interactive with a small @samp{p} so the prefix
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18712 argument is processed and passed to the function. The command can
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18713 only be used after a previous yank; otherwise an error message is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18714 sent. This check uses the variable @code{last-command} which is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18715 discussed elsewhere. (@xref{copy-region-as-kill}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18716
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18717 The @code{let} clause sets the variable @code{before} to true or false
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18718 depending whether point is before or after mark and then the region
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18719 between point and mark is deleted. This is the region that was just
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18720 inserted by the previous yank and it is this text that will be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18721 replaced. Next the @code{kill-ring-yank-pointer} is rotated so that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18722 the previously inserted text is not reinserted yet again. Mark is set
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18723 at the beginning of the place the new text will be inserted and then
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18724 the first element to which @code{kill-ring-yank-pointer} points is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18725 inserted. This leaves point after the new text. If in the previous
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18726 yank, point was left before the inserted text, point and mark are now
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18727 exchanged so point is again left in front of the newly inserted text.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18728 That is all there is to it!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18729
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18730 @node Full Graph, GNU Free Documentation License, Kill Ring, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18731 @appendix A Graph with Labelled Axes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18732
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18733 Printed axes help you understand a graph. They convey scale. In an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18734 earlier chapter (@pxref{Readying a Graph, , Readying a Graph}), we
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18735 wrote the code to print the body of a graph. Here we write the code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18736 for printing and labelling vertical and horizontal axes, along with the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18737 body itself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18738
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18739 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18740 * Labelled Example::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18741 * print-graph Varlist:: @code{let} expression in @code{print-graph}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18742 * print-Y-axis:: Print a label for the vertical axis.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18743 * print-X-axis:: Print a horizontal label.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18744 * Print Whole Graph:: The function to print a complete graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18745 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18746
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18747 @node Labelled Example, print-graph Varlist, Full Graph, Full Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18748 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18749 @unnumberedsec Labelled Example Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18750 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18751
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18752 Since insertions fill a buffer to the right and below point, the new
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18753 graph printing function should first print the Y or vertical axis,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18754 then the body of the graph, and finally the X or horizontal axis.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18755 This sequence lays out for us the contents of the function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18756
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18757 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18758 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18759 Set up code.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18760
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18761 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18762 Print Y axis.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18763
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18764 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18765 Print body of graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18766
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18767 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18768 Print X axis.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18769 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18770
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18771 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18772 Here is an example of how a finished graph should look:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18773
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18774 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18775 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18776 10 -
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18777 *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18778 * *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18779 * **
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18780 * ***
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18781 5 - * *******
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18782 * *** *******
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18783 *************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18784 ***************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18785 1 - ****************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18786 | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18787 1 5 10 15
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18788 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18789 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18790
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18791 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18792 In this graph, both the vertical and the horizontal axes are labelled
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18793 with numbers. However, in some graphs, the horizontal axis is time
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18794 and would be better labelled with months, like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18795
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18796 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18797 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18798 5 - *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18799 * ** *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18800 *******
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18801 ********** **
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18802 1 - **************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18803 | ^ |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18804 Jan June Jan
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18805 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18806 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18807
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18808 Indeed, with a little thought, we can easily come up with a variety of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18809 vertical and horizontal labelling schemes. Our task could become
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18810 complicated. But complications breed confusion. Rather than permit
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18811 this, it is better choose a simple labelling scheme for our first
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18812 effort, and to modify or replace it later.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18813
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18814 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18815 These considerations suggest the following outline for the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18816 @code{print-graph} function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18817
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18818 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18819 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18820 (defun print-graph (numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18821 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18822 (let ((height @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18823 @dots{}))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18824 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18825 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18826 (print-Y-axis height @dots{} )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18827 (graph-body-print numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18828 (print-X-axis @dots{} )))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18829 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18830 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18831
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18832 We can work on each part of the @code{print-graph} function definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18833 in turn.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18834
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18835 @node print-graph Varlist, print-Y-axis, Labelled Example, Full Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18836 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18837 @appendixsec The @code{print-graph} Varlist
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18838 @cindex @code{print-graph} varlist
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18839
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18840 In writing the @code{print-graph} function, the first task is to write
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18841 the varlist in the @code{let} expression. (We will leave aside for the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18842 moment any thoughts about making the function interactive or about the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18843 contents of its documentation string.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18844
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18845 The varlist should set several values. Clearly, the top of the label
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18846 for the vertical axis must be at least the height of the graph, which
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18847 means that we must obtain this information here. Note that the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18848 @code{print-graph-body} function also requires this information. There
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18849 is no reason to calculate the height of the graph in two different
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18850 places, so we should change @code{print-graph-body} from the way we
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18851 defined it earlier to take advantage of the calculation.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18852
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18853 Similarly, both the function for printing the X axis labels and the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18854 @code{print-graph-body} function need to learn the value of the width of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18855 each symbol. We can perform the calculation here and change the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18856 definition for @code{print-graph-body} from the way we defined it in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18857 previous chapter.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18858
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18859 The length of the label for the horizontal axis must be at least as long
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18860 as the graph. However, this information is used only in the function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18861 that prints the horizontal axis, so it does not need to be calculated here.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18862
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18863 These thoughts lead us directly to the following form for the varlist
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18864 in the @code{let} for @code{print-graph}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18865
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18866 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18867 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18868 (let ((height (apply 'max numbers-list)) ; @r{First version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18869 (symbol-width (length graph-blank)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18870 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18871 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18872
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18873 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18874 As we shall see, this expression is not quite right.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18875
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18876 @node print-Y-axis, print-X-axis, print-graph Varlist, Full Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18877 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18878 @appendixsec The @code{print-Y-axis} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18879 @cindex Axis, print vertical
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18880 @cindex Y axis printing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18881 @cindex Vertical axis printing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18882 @cindex Print vertical axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18883
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18884 The job of the @code{print-Y-axis} function is to print a label for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18885 the vertical axis that looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18886
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18887 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18888 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18889 10 -
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18890
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18891
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18892
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18893
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18894 5 -
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18895
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18896
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18897
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18898 1 -
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18899 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18900 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18901
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18902 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18903 The function should be passed the height of the graph, and then should
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18904 construct and insert the appropriate numbers and marks.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18905
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18906 It is easy enough to see in the figure what the Y axis label should
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18907 look like; but to say in words, and then to write a function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18908 definition to do the job is another matter. It is not quite true to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18909 say that we want a number and a tic every five lines: there are only
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18910 three lines between the @samp{1} and the @samp{5} (lines 2, 3, and 4),
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18911 but four lines between the @samp{5} and the @samp{10} (lines 6, 7, 8,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18912 and 9). It is better to say that we want a number and a tic mark on
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18913 the base line (number 1) and then that we want a number and a tic on
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18914 the fifth line from the bottom and on every line that is a multiple of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18915 five.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18916
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18917 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18918 * Height of label:: What height for the Y axis?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18919 * Compute a Remainder:: How to compute the remainder of a division.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18920 * Y Axis Element:: Construct a line for the Y axis.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18921 * Y-axis-column:: Generate a list of Y axis labels.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18922 * print-Y-axis Penultimate:: A not quite final version.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18923 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18924
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18925 @node Height of label, Compute a Remainder, print-Y-axis, print-Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18926 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18927 @unnumberedsubsec What height should the label be?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18928 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18929
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18930 The next issue is what height the label should be? Suppose the maximum
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18931 height of tallest column of the graph is seven. Should the highest
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18932 label on the Y axis be @samp{5 -}, and should the graph stick up above
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18933 the label? Or should the highest label be @samp{7 -}, and mark the peak
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18934 of the graph? Or should the highest label be @code{10 -}, which is a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18935 multiple of five, and be higher than the topmost value of the graph?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18936
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18937 The latter form is preferred. Most graphs are drawn within rectangles
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18938 whose sides are an integral number of steps long---5, 10, 15, and so
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18939 on for a step distance of five. But as soon as we decide to use a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18940 step height for the vertical axis, we discover that the simple
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18941 expression in the varlist for computing the height is wrong. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18942 expression is @code{(apply 'max numbers-list)}. This returns the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18943 precise height, not the maximum height plus whatever is necessary to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18944 round up to the nearest multiple of five. A more complex expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18945 is required.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18946
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18947 As usual in cases like this, a complex problem becomes simpler if it is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18948 divided into several smaller problems.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18949
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18950 First, consider the case when the highest value of the graph is an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18951 integral multiple of five---when it is 5, 10, 15 ,or some higher
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18952 multiple of five. We can use this value as the Y axis height.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18953
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18954 A fairly simply way to determine whether a number is a multiple of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18955 five is to divide it by five and see if the division results in a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18956 remainder. If there is no remainder, the number is a multiple of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18957 five. Thus, seven divided by five has a remainder of two, and seven
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18958 is not an integral multiple of five. Put in slightly different
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18959 language, more reminiscent of the classroom, five goes into seven
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18960 once, with a remainder of two. However, five goes into ten twice,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18961 with no remainder: ten is an integral multiple of five.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18962
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18963 @node Compute a Remainder, Y Axis Element, Height of label, print-Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18964 @appendixsubsec Side Trip: Compute a Remainder
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18965
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18966 @findex % @r{(remainder function)}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18967 @cindex Remainder function, @code{%}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18968 In Lisp, the function for computing a remainder is @code{%}. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18969 function returns the remainder of its first argument divided by its
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18970 second argument. As it happens, @code{%} is a function in Emacs Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18971 that you cannot discover using @code{apropos}: you find nothing if you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18972 type @kbd{M-x apropos @key{RET} remainder @key{RET}}. The only way to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18973 learn of the existence of @code{%} is to read about it in a book such
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18974 as this or in the Emacs Lisp sources. The @code{%} function is used
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18975 in the code for @code{rotate-yank-pointer}, which is described in an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18976 appendix. (@xref{rotate-yk-ptr body, , The Body of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18977 @code{rotate-yank-pointer}}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18978
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18979 You can try the @code{%} function by evaluating the following two
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18980 expressions:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18981
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18982 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18983 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18984 (% 7 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18985
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18986 (% 10 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18987 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18988 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18989
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18990 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18991 The first expression returns 2 and the second expression returns 0.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18992
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18993 To test whether the returned value is zero or some other number, we
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18994 can use the @code{zerop} function. This function returns @code{t} if
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18995 its argument, which must be a number, is zero.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18996
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18997 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18998 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18999 (zerop (% 7 5))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19000 @result{} nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19001
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19002 (zerop (% 10 5))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19003 @result{} t
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19004 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19005 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19006
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19007 Thus, the following expression will return @code{t} if the height
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19008 of the graph is evenly divisible by five:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19009
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19010 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19011 (zerop (% height 5))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19012 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19013
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19014 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19015 (The value of @code{height}, of course, can be found from @code{(apply
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19016 'max numbers-list)}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19017
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19018 On the other hand, if the value of @code{height} is not a multiple of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19019 five, we want to reset the value to the next higher multiple of five.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19020 This is straightforward arithmetic using functions with which we are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19021 already familiar. First, we divide the value of @code{height} by five
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19022 to determine how many times five goes into the number. Thus, five
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19023 goes into twelve twice. If we add one to this quotient and multiply by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19024 five, we will obtain the value of the next multiple of five that is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19025 larger than the height. Five goes into twelve twice. Add one to two,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19026 and multiply by five; the result is fifteen, which is the next multiple
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19027 of five that is higher than twelve. The Lisp expression for this is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19028
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19029 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19030 (* (1+ (/ height 5)) 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19031 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19032
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19033 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19034 For example, if you evaluate the following, the result is 15:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19035
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19036 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19037 (* (1+ (/ 12 5)) 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19038 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19039
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19040 All through this discussion, we have been using `five' as the value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19041 for spacing labels on the Y axis; but we may want to use some other
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19042 value. For generality, we should replace `five' with a variable to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19043 which we can assign a value. The best name I can think of for this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19044 variable is @code{Y-axis-label-spacing}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19045
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19046 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19047 Using this term, and an @code{if} expression, we produce the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19048 following:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19049
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19050 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19051 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19052 (if (zerop (% height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19053 height
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19054 ;; @r{else}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19055 (* (1+ (/ height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19056 Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19057 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19058 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19059
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19060 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19061 This expression returns the value of @code{height} itself if the height
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19062 is an even multiple of the value of the @code{Y-axis-label-spacing} or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19063 else it computes and returns a value of @code{height} that is equal to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19064 the next higher multiple of the value of the @code{Y-axis-label-spacing}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19065
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19066 We can now include this expression in the @code{let} expression of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19067 @code{print-graph} function (after first setting the value of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19068 @code{Y-axis-label-spacing}):
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19069 @vindex Y-axis-label-spacing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19070
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19071 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19072 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19073 (defvar Y-axis-label-spacing 5
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19074 "Number of lines from one Y axis label to next.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19075 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19076
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19077 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19078 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19079 (let* ((height (apply 'max numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19080 (height-of-top-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19081 (if (zerop (% height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19082 height
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19083 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19084 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19085 ;; @r{else}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19086 (* (1+ (/ height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19087 Y-axis-label-spacing)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19088 (symbol-width (length graph-blank))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19089 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19090 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19091 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19092
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19093 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19094 (Note use of the @code{let*} function: the initial value of height is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19095 computed once by the @code{(apply 'max numbers-list)} expression and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19096 then the resulting value of @code{height} is used to compute its
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19097 final value. @xref{fwd-para let, , The @code{let*} expression}, for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19098 more about @code{let*}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19099
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19100 @node Y Axis Element, Y-axis-column, Compute a Remainder, print-Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19101 @appendixsubsec Construct a Y Axis Element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19102
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19103 When we print the vertical axis, we want to insert strings such as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19104 @w{@samp{5 -}} and @w{@samp{10 - }} every five lines.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19105 Moreover, we want the numbers and dashes to line up, so shorter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19106 numbers must be padded with leading spaces. If some of the strings
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19107 use two digit numbers, the strings with single digit numbers must
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19108 include a leading blank space before the number.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19109
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19110 @findex number-to-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19111 To figure out the length of the number, the @code{length} function is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19112 used. But the @code{length} function works only with a string, not with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19113 a number. So the number has to be converted from being a number to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19114 being a string. This is done with the @code{number-to-string} function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19115 For example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19116
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19117 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19118 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19119 (length (number-to-string 35))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19120 @result{} 2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19121
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19122 (length (number-to-string 100))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19123 @result{} 3
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19124 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19125 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19126
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19127 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19128 (@code{number-to-string} is also called @code{int-to-string}; you will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19129 see this alternative name in various sources.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19130
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19131 In addition, in each label, each number is followed by a string such
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19132 as @w{@samp{ - }}, which we will call the @code{Y-axis-tic} marker.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19133 This variable is defined with @code{defvar}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19134
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19135 @vindex Y-axis-tic
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19136 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19137 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19138 (defvar Y-axis-tic " - "
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19139 "String that follows number in a Y axis label.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19140 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19141 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19142
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19143 The length of the Y label is the sum of the length of the Y axis tic
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19144 mark and the length of the number of the top of the graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19145
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19146 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19147 (length (concat (number-to-string height) Y-axis-tic)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19148 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19149
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19150 This value will be calculated by the @code{print-graph} function in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19151 its varlist as @code{full-Y-label-width} and passed on. (Note that we
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19152 did not think to include this in the varlist when we first proposed it.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19153
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19154 To make a complete vertical axis label, a tic mark is concatenated
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19155 with a number; and the two together may be preceded by one or more
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19156 spaces depending on how long the number is. The label consists of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19157 three parts: the (optional) leading spaces, the number, and the tic
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19158 mark. The function is passed the value of the number for the specific
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19159 row, and the value of the width of the top line, which is calculated
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19160 (just once) by @code{print-graph}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19161
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19162 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19163 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19164 (defun Y-axis-element (number full-Y-label-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19165 "Construct a NUMBERed label element.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19166 A numbered element looks like this ` 5 - ',
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19167 and is padded as needed so all line up with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19168 the element for the largest number."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19169 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19170 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19171 (let* ((leading-spaces
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19172 (- full-Y-label-width
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19173 (length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19174 (concat (number-to-string number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19175 Y-axis-tic)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19176 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19177 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19178 (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19179 (make-string leading-spaces ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19180 (number-to-string number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19181 Y-axis-tic)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19182 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19183 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19184
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19185 The @code{Y-axis-element} function concatenates together the leading
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19186 spaces, if any; the number, as a string; and the tic mark.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19187
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19188 To figure out how many leading spaces the label will need, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19189 function subtracts the actual length of the label---the length of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19190 number plus the length of the tic mark---from the desired label width.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19191
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19192 @findex make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19193 Blank spaces are inserted using the @code{make-string} function. This
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19194 function takes two arguments: the first tells it how long the string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19195 will be and the second is a symbol for the character to insert, in a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19196 special format. The format is a question mark followed by a blank
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19197 space, like this, @samp{? }. @xref{Character Type, , Character Type,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19198 elisp, The GNU Emacs Lisp Reference Manual}, for a description of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19199 syntax for characters.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19201 The @code{number-to-string} function is used in the concatenation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19202 expression, to convert the number to a string that is concatenated
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19203 with the leading spaces and the tic mark.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19204
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19205 @node Y-axis-column, print-Y-axis Penultimate, Y Axis Element, print-Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19206 @appendixsubsec Create a Y Axis Column
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19207
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19208 The preceding functions provide all the tools needed to construct a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19209 function that generates a list of numbered and blank strings to insert
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19210 as the label for the vertical axis:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19211
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19212 @findex Y-axis-column
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19213 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19214 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19215 (defun Y-axis-column (height width-of-label)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19216 "Construct list of Y axis labels and blank strings.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19217 For HEIGHT of line above base and WIDTH-OF-LABEL."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19218 (let (Y-axis)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19219 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19220 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19221 (while (> height 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19222 (if (zerop (% height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19223 ;; @r{Insert label.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19224 (setq Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19225 (cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19226 (Y-axis-element height width-of-label)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19227 Y-axis))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19228 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19229 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19230 ;; @r{Else, insert blanks.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19231 (setq Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19232 (cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19233 (make-string width-of-label ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19234 Y-axis)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19235 (setq height (1- height)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19236 ;; @r{Insert base line.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19237 (setq Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19238 (cons (Y-axis-element 1 width-of-label) Y-axis))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19239 (nreverse Y-axis)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19240 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19241 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19242
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19243 In this function, we start with the value of @code{height} and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19244 repetitively subtract one from its value. After each subtraction, we
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19245 test to see whether the value is an integral multiple of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19246 @code{Y-axis-label-spacing}. If it is, we construct a numbered label
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19247 using the @code{Y-axis-element} function; if not, we construct a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19248 blank label using the @code{make-string} function. The base line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19249 consists of the number one followed by a tic mark.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19251 @node print-Y-axis Penultimate, , Y-axis-column, print-Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19252 @appendixsubsec The Not Quite Final Version of @code{print-Y-axis}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19253
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19254 The list constructed by the @code{Y-axis-column} function is passed to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19255 the @code{print-Y-axis} function, which inserts the list as a column.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19256
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19257 @findex print-Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19258 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19259 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19260 (defun print-Y-axis (height full-Y-label-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19261 "Insert Y axis using HEIGHT and FULL-Y-LABEL-WIDTH.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19262 Height must be the maximum height of the graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19263 Full width is the width of the highest label element."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19264 ;; Value of height and full-Y-label-width
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19265 ;; are passed by `print-graph'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19266 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19267 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19268 (let ((start (point)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19269 (insert-rectangle
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19270 (Y-axis-column height full-Y-label-width))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19271 ;; @r{Place point ready for inserting graph.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19272 (goto-char start)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19273 ;; @r{Move point forward by value of} full-Y-label-width
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19274 (forward-char full-Y-label-width)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19275 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19276 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19277
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19278 The @code{print-Y-axis} uses the @code{insert-rectangle} function to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19279 insert the Y axis labels created by the @code{Y-axis-column} function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19280 In addition, it places point at the correct position for printing the body of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19281 the graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19282
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19283 You can test @code{print-Y-axis}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19284
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19285 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19286 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19287 Install
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19288
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19289 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19290 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19291 Y-axis-label-spacing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19292 Y-axis-tic
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19293 Y-axis-element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19294 Y-axis-column
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19295 print-Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19296 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19297 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19298
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19299 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19300 Copy the following expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19301
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19302 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19303 (print-Y-axis 12 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19304 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19305
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19306 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19307 Switch to the @file{*scratch*} buffer and place the cursor where you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19308 want the axis labels to start.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19309
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19310 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19311 Type @kbd{M-:} (@code{eval-expression}).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19312
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19313 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19314 Yank the @code{graph-body-print} expression into the minibuffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19315 with @kbd{C-y} (@code{yank)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19316
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19317 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19318 Press @key{RET} to evaluate the expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19319 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19320
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19321 Emacs will print labels vertically, the top one being
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19322 @w{@samp{10 -@w{ }}}. (The @code{print-graph} function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19323 will pass the value of @code{height-of-top-line}, which
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19324 in this case would end up as 15.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19325
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19326 @node print-X-axis, Print Whole Graph, print-Y-axis, Full Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19327 @appendixsec The @code{print-X-axis} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19328 @cindex Axis, print horizontal
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19329 @cindex X axis printing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19330 @cindex Print horizontal axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19331 @cindex Horizontal axis printing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19332
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19333 X axis labels are much like Y axis labels, except that the tics are on a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19334 line above the numbers. Labels should look like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19335
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19336 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19337 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19338 | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19339 1 5 10 15
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19340 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19341 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19342
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19343 The first tic is under the first column of the graph and is preceded by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19344 several blank spaces. These spaces provide room in rows above for the Y
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19345 axis labels. The second, third, fourth, and subsequent tics are all
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19346 spaced equally, according to the value of @code{X-axis-label-spacing}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19347
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19348 The second row of the X axis consists of numbers, preceded by several
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19349 blank spaces and also separated according to the value of the variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19350 @code{X-axis-label-spacing}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19351
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19352 The value of the variable @code{X-axis-label-spacing} should itself be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19353 measured in units of @code{symbol-width}, since you may want to change
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19354 the width of the symbols that you are using to print the body of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19355 graph without changing the ways the graph is labelled.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19356
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19357 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19358 * Similarities differences:: Much like @code{print-Y-axis}, but not exactly.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19359 * X Axis Tic Marks:: Create tic marks for the horizontal axis.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19360 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19361
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19362 @node Similarities differences, X Axis Tic Marks, print-X-axis, print-X-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19363 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19364 @unnumberedsubsec Similarities and differences
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19365 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19366
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19367 The @code{print-X-axis} function is constructed in more or less the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19368 same fashion as the @code{print-Y-axis} function except that it has
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19369 two lines: the line of tic marks and the numbers. We will write a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19370 separate function to print each line and then combine them within the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19371 @code{print-X-axis} function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19372
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19373 This is a three step process:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19374
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19375 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19376 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19377 Write a function to print the X axis tic marks, @code{print-X-axis-tic-line}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19378
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19379 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19380 Write a function to print the X numbers, @code{print-X-axis-numbered-line}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19381
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19382 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19383 Write a function to print both lines, the @code{print-X-axis} function,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19384 using @code{print-X-axis-tic-line} and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19385 @code{print-X-axis-numbered-line}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19386 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19387
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19388 @node X Axis Tic Marks, , Similarities differences, print-X-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19389 @appendixsubsec X Axis Tic Marks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19390
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19391 The first function should print the X axis tic marks. We must specify
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19392 the tic marks themselves and their spacing:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19393
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19394 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19395 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19396 (defvar X-axis-label-spacing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19397 (if (boundp 'graph-blank)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19398 (* 5 (length graph-blank)) 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19399 "Number of units from one X axis label to next.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19400 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19401 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19402
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19403 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19404 (Note that the value of @code{graph-blank} is set by another
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19405 @code{defvar}. The @code{boundp} predicate checks whether it has
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19406 already been set; @code{boundp} returns @code{nil} if it has not.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19407 If @code{graph-blank} were unbound and we did not use this conditional
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19408 construction, in GNU Emacs 21, we would enter the debugger and see an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19409 error message saying
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19410 @samp{@w{Debugger entered--Lisp error:} @w{(void-variable graph-blank)}}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19411
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19412 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19413 Here is the @code{defvar} for @code{X-axis-tic-symbol}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19414
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19415 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19416 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19417 (defvar X-axis-tic-symbol "|"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19418 "String to insert to point to a column in X axis.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19419 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19420 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19422 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19423 The goal is to make a line that looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19424
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19425 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19426 | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19427 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19428
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19429 The first tic is indented so that it is under the first column, which is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19430 indented to provide space for the Y axis labels.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19431
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19432 A tic element consists of the blank spaces that stretch from one tic to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19433 the next plus a tic symbol. The number of blanks is determined by the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19434 width of the tic symbol and the @code{X-axis-label-spacing}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19435
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19436 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19437 The code looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19438
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19439 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19440 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19441 ;;; X-axis-tic-element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19442 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19443 (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19444 (make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19445 ;; @r{Make a string of blanks.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19446 (- (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19447 (length X-axis-tic-symbol))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19448 ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19449 ;; @r{Concatenate blanks with tic symbol.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19450 X-axis-tic-symbol)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19451 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19452 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19453 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19454
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19455 Next, we determine how many blanks are needed to indent the first tic
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19456 mark to the first column of the graph. This uses the value of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19457 @code{full-Y-label-width} passed it by the @code{print-graph} function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19458
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19459 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19460 The code to make @code{X-axis-leading-spaces}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19461 looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19462
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19463 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19464 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19465 ;; X-axis-leading-spaces
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19466 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19467 (make-string full-Y-label-width ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19468 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19469 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19470 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19471
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19472 We also need to determine the length of the horizontal axis, which is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19473 the length of the numbers list, and the number of tics in the horizontal
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19474 axis:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19475
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19476 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19477 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19478 ;; X-length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19479 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19480 (length numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19481 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19482
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19483 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19484 ;; tic-width
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19485 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19486 (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19487 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19488
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19489 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19490 ;; number-of-X-tics
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19491 (if (zerop (% (X-length tic-width)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19492 (/ (X-length tic-width))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19493 (1+ (/ (X-length tic-width))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19494 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19495 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19496
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19497 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19498 All this leads us directly to the function for printing the X axis tic line:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19499
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19500 @findex print-X-axis-tic-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19501 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19502 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19503 (defun print-X-axis-tic-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19504 (number-of-X-tics X-axis-leading-spaces X-axis-tic-element)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19505 "Print tics for X axis."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19506 (insert X-axis-leading-spaces)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19507 (insert X-axis-tic-symbol) ; @r{Under first column.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19508 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19509 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19510 ;; @r{Insert second tic in the right spot.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19511 (insert (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19512 (make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19513 (- (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19514 ;; @r{Insert white space up to second tic symbol.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19515 (* 2 (length X-axis-tic-symbol)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19516 ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19517 X-axis-tic-symbol))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19518 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19519 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19520 ;; @r{Insert remaining tics.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19521 (while (> number-of-X-tics 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19522 (insert X-axis-tic-element)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19523 (setq number-of-X-tics (1- number-of-X-tics))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19524 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19525 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19526
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19527 The line of numbers is equally straightforward:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19528
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19529 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19530 First, we create a numbered element with blank spaces before each number:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19531
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19532 @findex X-axis-element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19533 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19534 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19535 (defun X-axis-element (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19536 "Construct a numbered X axis element."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19537 (let ((leading-spaces
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19538 (- (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19539 (length (number-to-string number)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19540 (concat (make-string leading-spaces ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19541 (number-to-string number))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19542 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19543 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19544
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19545 Next, we create the function to print the numbered line, starting with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19546 the number ``1'' under the first column:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19547
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19548 @findex print-X-axis-numbered-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19549 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19550 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19551 (defun print-X-axis-numbered-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19552 (number-of-X-tics X-axis-leading-spaces)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19553 "Print line of X-axis numbers"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19554 (let ((number X-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19555 (insert X-axis-leading-spaces)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19556 (insert "1")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19557 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19558 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19559 (insert (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19560 (make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19561 ;; @r{Insert white space up to next number.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19562 (- (* symbol-width X-axis-label-spacing) 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19563 ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19564 (number-to-string number)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19565 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19566 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19567 ;; @r{Insert remaining numbers.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19568 (setq number (+ number X-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19569 (while (> number-of-X-tics 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19570 (insert (X-axis-element number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19571 (setq number (+ number X-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19572 (setq number-of-X-tics (1- number-of-X-tics)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19573 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19574 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19575
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19576 Finally, we need to write the @code{print-X-axis} that uses
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19577 @code{print-X-axis-tic-line} and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19578 @code{print-X-axis-numbered-line}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19579
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19580 The function must determine the local values of the variables used by both
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19581 @code{print-X-axis-tic-line} and @code{print-X-axis-numbered-line}, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19582 then it must call them. Also, it must print the carriage return that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19583 separates the two lines.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19584
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19585 The function consists of a varlist that specifies five local variables,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19586 and calls to each of the two line printing functions:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19587
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19588 @findex print-X-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19589 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19590 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19591 (defun print-X-axis (numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19592 "Print X axis labels to length of NUMBERS-LIST."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19593 (let* ((leading-spaces
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19594 (make-string full-Y-label-width ? ))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19595 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19596 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19597 ;; symbol-width @r{is provided by} graph-body-print
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19598 (tic-width (* symbol-width X-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19599 (X-length (length numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19600 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19601 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19602 (X-tic
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19603 (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19604 (make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19605 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19606 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19607 ;; @r{Make a string of blanks.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19608 (- (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19609 (length X-axis-tic-symbol))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19610 ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19611 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19612 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19613 ;; @r{Concatenate blanks with tic symbol.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19614 X-axis-tic-symbol))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19615 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19616 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19617 (tic-number
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19618 (if (zerop (% X-length tic-width))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19619 (/ X-length tic-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19620 (1+ (/ X-length tic-width)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19621 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19622 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19623 (print-X-axis-tic-line tic-number leading-spaces X-tic)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19624 (insert "\n")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19625 (print-X-axis-numbered-line tic-number leading-spaces)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19626 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19627 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19628
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19629 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19630 You can test @code{print-X-axis}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19631
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19632 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19633 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19634 Install @code{X-axis-tic-symbol}, @code{X-axis-label-spacing},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19635 @code{print-X-axis-tic-line}, as well as @code{X-axis-element},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19636 @code{print-X-axis-numbered-line}, and @code{print-X-axis}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19637
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19638 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19639 Copy the following expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19640
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19641 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19642 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19643 (progn
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19644 (let ((full-Y-label-width 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19645 (symbol-width 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19646 (print-X-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19647 '(1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19648 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19649 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19650
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19651 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19652 Switch to the @file{*scratch*} buffer and place the cursor where you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19653 want the axis labels to start.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19654
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19655 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19656 Type @kbd{M-:} (@code{eval-expression}).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19657
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19658 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19659 Yank the test expression into the minibuffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19660 with @kbd{C-y} (@code{yank)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19661
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19662 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19663 Press @key{RET} to evaluate the expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19664 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19665
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19666 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19667 Emacs will print the horizontal axis like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19668
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19669 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19670 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19671 | | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19672 1 5 10 15 20
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19673 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19674 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19675
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19676 @node Print Whole Graph, , print-X-axis, Full Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19677 @appendixsec Printing the Whole Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19678 @cindex Printing the whole graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19679 @cindex Whole graph printing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19680 @cindex Graph, printing all
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19681
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19682 Now we are nearly ready to print the whole graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19683
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19684 The function to print the graph with the proper labels follows the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19685 outline we created earlier (@pxref{Full Graph, , A Graph with Labelled
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19686 Axes}), but with additions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19687
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19688 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19689 Here is the outline:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19690
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19691 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19692 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19693 (defun print-graph (numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19694 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19695 (let ((height @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19696 @dots{}))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19697 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19698 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19699 (print-Y-axis height @dots{} )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19700 (graph-body-print numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19701 (print-X-axis @dots{} )))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19702 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19703 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19704
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19705 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19706 * The final version:: A few changes.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19707 * Test print-graph:: Run a short test.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19708 * Graphing words in defuns:: Executing the final code.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19709 * lambda:: How to write an anonymous function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19710 * mapcar:: Apply a function to elements of a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19711 * Another Bug:: Yet another bug @dots{} most insidious.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19712 * Final printed graph:: The graph itself!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19713 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19714
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19715 @node The final version, Test print-graph, Print Whole Graph, Print Whole Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19716 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19717 @unnumberedsubsec Changes for the Final Version
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19718 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19719
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19720 The final version is different from what we planned in two ways:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19721 first, it contains additional values calculated once in the varlist;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19722 second, it carries an option to specify the labels' increment per row.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19723 This latter feature turns out to be essential; otherwise, a graph may
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19724 have more rows than fit on a display or on a sheet of paper.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19725
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19726 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19727 This new feature requires a change to the @code{Y-axis-column}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19728 function, to add @code{vertical-step} to it. The function looks like
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19729 this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19730
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19731 @findex Y-axis-column @r{Final version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19732 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19733 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19734 ;;; @r{Final version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19735 (defun Y-axis-column
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19736 (height width-of-label &optional vertical-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19737 "Construct list of labels for Y axis.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19738 HEIGHT is maximum height of graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19739 WIDTH-OF-LABEL is maximum width of label.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19740 VERTICAL-STEP, an option, is a positive integer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19741 that specifies how much a Y axis label increments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19742 for each line. For example, a step of 5 means
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19743 that each line is five units of the graph."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19744 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19745 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19746 (let (Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19747 (number-per-line (or vertical-step 1)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19748 (while (> height 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19749 (if (zerop (% height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19750 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19751 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19752 ;; @r{Insert label.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19753 (setq Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19754 (cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19755 (Y-axis-element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19756 (* height number-per-line)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19757 width-of-label)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19758 Y-axis))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19759 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19760 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19761 ;; @r{Else, insert blanks.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19762 (setq Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19763 (cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19764 (make-string width-of-label ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19765 Y-axis)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19766 (setq height (1- height)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19767 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19768 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19769 ;; @r{Insert base line.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19770 (setq Y-axis (cons (Y-axis-element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19771 (or vertical-step 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19772 width-of-label)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19773 Y-axis))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19774 (nreverse Y-axis)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19775 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19776 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19777
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19778 The values for the maximum height of graph and the width of a symbol
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19779 are computed by @code{print-graph} in its @code{let} expression; so
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19780 @code{graph-body-print} must be changed to accept them.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19781
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19782 @findex graph-body-print @r{Final version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19783 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19784 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19785 ;;; @r{Final version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19786 (defun graph-body-print (numbers-list height symbol-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19787 "Print a bar graph of the NUMBERS-LIST.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19788 The numbers-list consists of the Y-axis values.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19789 HEIGHT is maximum height of graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19790 SYMBOL-WIDTH is number of each column."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19791 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19792 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19793 (let (from-position)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19794 (while numbers-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19795 (setq from-position (point))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19796 (insert-rectangle
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19797 (column-of-graph height (car numbers-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19798 (goto-char from-position)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19799 (forward-char symbol-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19800 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19801 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19802 ;; @r{Draw graph column by column.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19803 (sit-for 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19804 (setq numbers-list (cdr numbers-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19805 ;; @r{Place point for X axis labels.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19806 (forward-line height)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19807 (insert "\n")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19808 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19809 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19810
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19811 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19812 Finally, the code for the @code{print-graph} function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19813
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19814 @findex print-graph @r{Final version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19815 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19816 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19817 ;;; @r{Final version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19818 (defun print-graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19819 (numbers-list &optional vertical-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19820 "Print labelled bar graph of the NUMBERS-LIST.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19821 The numbers-list consists of the Y-axis values.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19822 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19823
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19824 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19825 Optionally, VERTICAL-STEP, a positive integer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19826 specifies how much a Y axis label increments for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19827 each line. For example, a step of 5 means that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19828 each row is five units."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19829 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19830 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19831 (let* ((symbol-width (length graph-blank))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19832 ;; @code{height} @r{is both the largest number}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19833 ;; @r{and the number with the most digits.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19834 (height (apply 'max numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19835 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19836 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19837 (height-of-top-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19838 (if (zerop (% height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19839 height
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19840 ;; @r{else}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19841 (* (1+ (/ height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19842 Y-axis-label-spacing)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19843 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19844 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19845 (vertical-step (or vertical-step 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19846 (full-Y-label-width
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19847 (length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19848 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19849 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19850 (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19851 (number-to-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19852 (* height-of-top-line vertical-step))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19853 Y-axis-tic))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19854 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19855
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19856 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19857 (print-Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19858 height-of-top-line full-Y-label-width vertical-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19859 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19860 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19861 (graph-body-print
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19862 numbers-list height-of-top-line symbol-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19863 (print-X-axis numbers-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19864 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19865 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19866
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19867 @node Test print-graph, Graphing words in defuns, The final version, Print Whole Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19868 @appendixsubsec Testing @code{print-graph}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19869
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19870 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19871 We can test the @code{print-graph} function with a short list of numbers:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19872
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19873 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19874 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19875 Install the final versions of @code{Y-axis-column},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19876 @code{graph-body-print}, and @code{print-graph} (in addition to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19877 rest of the code.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19878
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19879 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19880 Copy the following expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19881
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19882 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19883 (print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19884 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19885
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19886 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19887 Switch to the @file{*scratch*} buffer and place the cursor where you
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19888 want the axis labels to start.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19889
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19890 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19891 Type @kbd{M-:} (@code{eval-expression}).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19892
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19893 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19894 Yank the test expression into the minibuffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19895 with @kbd{C-y} (@code{yank)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19896
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19897 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19898 Press @key{RET} to evaluate the expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19899 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19900
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19901 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19902 Emacs will print a graph that looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19903
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19904 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19905 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19906 10 -
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19907
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19908
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19909 *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19910 ** *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19911 5 - **** *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19912 **** ***
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19913 * *********
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19914 ************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19915 1 - *************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19916
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19917 | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19918 1 5 10 15
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19919 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19920 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19921
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19922 On the other hand, if you pass @code{print-graph} a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19923 @code{vertical-step} value of 2, by evaluating this expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19924
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19925 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19926 (print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1) 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19927 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19928
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19929 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19930 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19931 The graph looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19932
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19933 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19934 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19935 20 -
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19936
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19937
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19938 *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19939 ** *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19940 10 - **** *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19941 **** ***
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19942 * *********
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19943 ************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19944 2 - *************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19945
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19946 | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19947 1 5 10 15
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19948 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19949 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19950
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19951 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19952 (A question: is the `2' on the bottom of the vertical axis a bug or a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19953 feature? If you think it is a bug, and should be a `1' instead, (or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19954 even a `0'), you can modify the sources.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19955
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19956 @node Graphing words in defuns, lambda, Test print-graph, Print Whole Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19957 @appendixsubsec Graphing Numbers of Words and Symbols
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19958
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19959 Now for the graph for which all this code was written: a graph that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19960 shows how many function definitions contain fewer than 10 words and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19961 symbols, how many contain between 10 and 19 words and symbols, how
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19962 many contain between 20 and 29 words and symbols, and so on.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19963
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19964 This is a multi-step process. First make sure you have loaded all the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19965 requisite code.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19966
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19967 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19968 It is a good idea to reset the value of @code{top-of-ranges} in case
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19969 you have set it to some different value. You can evaluate the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19970 following:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19971
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19972 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19973 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19974 (setq top-of-ranges
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19975 '(10 20 30 40 50
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19976 60 70 80 90 100
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19977 110 120 130 140 150
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19978 160 170 180 190 200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19979 210 220 230 240 250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19980 260 270 280 290 300)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19981 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19982 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19983
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19984 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19985 Next create a list of the number of words and symbols in each range.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19986
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19987 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19988 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19989 Evaluate the following:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19990
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19991 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19992 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19993 (setq list-for-graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19994 (defuns-per-range
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19995 (sort
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19996 (recursive-lengths-list-many-files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19997 (directory-files "/usr/local/emacs/lisp"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19998 t ".+el$"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19999 '<)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20000 top-of-ranges))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20001 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20002 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20003
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20004 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20005 On my machine, this takes about an hour. It looks though 303 Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20006 files in my copy of Emacs version 19.23. After all that computing,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20007 the @code{list-for-graph} has this value:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20008
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20009 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20010 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20011 (537 1027 955 785 594 483 349 292 224 199 166 120 116 99
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20012 90 80 67 48 52 45 41 33 28 26 25 20 12 28 11 13 220)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20013 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20014 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20015
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20016 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20017 This means that my copy of Emacs has 537 function definitions with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20018 fewer than 10 words or symbols in them, 1,027 function definitions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20019 with 10 to 19 words or symbols in them, 955 function definitions with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20020 20 to 29 words or symbols in them, and so on.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20021
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20022 Clearly, just by looking at this list we can see that most function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20023 definitions contain ten to thirty words and symbols.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20024
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20025 Now for printing. We do @emph{not} want to print a graph that is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20026 1,030 lines high @dots{} Instead, we should print a graph that is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20027 fewer than twenty-five lines high. A graph that height can be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20028 displayed on almost any monitor, and easily printed on a sheet of paper.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20029
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20030 This means that each value in @code{list-for-graph} must be reduced to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20031 one-fiftieth its present value.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20032
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20033 Here is a short function to do just that, using two functions we have
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20034 not yet seen, @code{mapcar} and @code{lambda}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20035
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20036 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20037 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20038 (defun one-fiftieth (full-range)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20039 "Return list, each number one-fiftieth of previous."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20040 (mapcar '(lambda (arg) (/ arg 50)) full-range))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20041 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20042 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20043
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20044 @node lambda, mapcar, Graphing words in defuns, Print Whole Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20045 @appendixsubsec A @code{lambda} Expression: Useful Anonymity
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20046 @cindex Anonymous function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20047 @findex lambda
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20048
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20049 @code{lambda} is the symbol for an anonymous function, a function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20050 without a name. Every time you use an anonymous function, you need to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20051 include its whole body.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20052
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20053 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20054 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20055 Thus,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20056
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20057 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20058 (lambda (arg) (/ arg 50))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20059 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20060
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20061 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20062 is a function definition that says `return the value resulting from
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20063 dividing whatever is passed to me as @code{arg} by 50'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20064
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20065 Earlier, for example, we had a function @code{multiply-by-seven}; it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20066 multiplied its argument by 7. This function is similar, except it
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20067 divides its argument by 50; and, it has no name. The anonymous
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20068 equivalent of @code{multiply-by-seven} is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20069
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20070 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20071 (lambda (number) (* 7 number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20072 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20073
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20074 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20075 (@xref{defun, , The @code{defun} Special Form}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20076
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20077 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20078 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20079 If we want to multiply 3 by 7, we can write:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20080
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20081 @c !!! Clear print-postscript-figures if the computer formatting this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20082 @c document is too small and cannot handle all the diagrams and figures.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20083 @c clear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20084 @c set print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20085 @c lambda example diagram #1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20086 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20087 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20088 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20089 (multiply-by-seven 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20090 \_______________/ ^
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20091 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20092 function argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20093 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20094 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20095 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20096 @ifset print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20097 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20098 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20099 @image{lambda-1}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20100 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20101 % \input /usr/local/lib/tex/inputs/psfig.tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20102 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-1.eps}}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20103 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20104 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20105 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20106 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20107 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20108 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20109 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20110 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20111 (multiply-by-seven 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20112 \_______________/ ^
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20113 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20114 function argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20115 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20116 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20117 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20118 @end ifclear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20119
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20120 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20121 This expression returns 21.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20122
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20123 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20124 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20125 Similarly, we can write:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20126
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20127 @c lambda example diagram #2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20128 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20129 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20130 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20131 ((lambda (number) (* 7 number)) 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20132 \____________________________/ ^
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20133 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20134 anonymous function argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20135 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20136 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20137 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20138 @ifset print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20139 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20140 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20141 @image{lambda-2}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20142 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20143 % \input /usr/local/lib/tex/inputs/psfig.tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20144 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-2.eps}}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20145 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20146 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20147 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20148 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20149 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20150 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20151 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20152 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20153 ((lambda (number) (* 7 number)) 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20154 \____________________________/ ^
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20155 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20156 anonymous function argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20157 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20158 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20159 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20160 @end ifclear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20161
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20162 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20163 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20164 If we want to divide 100 by 50, we can write:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20165
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20166 @c lambda example diagram #3
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20167 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20168 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20169 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20170 ((lambda (arg) (/ arg 50)) 100)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20171 \______________________/ \_/
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20172 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20173 anonymous function argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20174 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20175 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20176 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20177 @ifset print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20178 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20179 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20180 @image{lambda-3}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20181 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20182 % \input /usr/local/lib/tex/inputs/psfig.tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20183 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-3.eps}}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20184 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20185 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20186 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20187 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20188 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20189 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20190 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20191 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20192 ((lambda (arg) (/ arg 50)) 100)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20193 \______________________/ \_/
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20194 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20195 anonymous function argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20196 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20197 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20198 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20199 @end ifclear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20201 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20202 This expression returns 2. The 100 is passed to the function, which
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20203 divides that number by 50.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20204
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20205 @xref{Lambda Expressions, , Lambda Expressions, elisp, The GNU Emacs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20206 Lisp Reference Manual}, for more about @code{lambda}. Lisp and lambda
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20207 expressions derive from the Lambda Calculus.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20208
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20209 @node mapcar, Another Bug, lambda, Print Whole Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20210 @appendixsubsec The @code{mapcar} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20211 @findex mapcar
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20212
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20213 @code{mapcar} is a function that calls its first argument with each
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20214 element of its second argument, in turn. The second argument must be
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20215 a sequence.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20216
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20217 The @samp{map} part of the name comes from the mathematical phrase,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20218 `mapping over a domain', meaning to apply a function to each of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20219 elements in a domain. The mathematical phrase is based on the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20220 metaphor of a surveyor walking, one step at a time, over an area he is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20221 mapping. And @samp{car}, of course, comes from the Lisp notion of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20222 first of a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20223
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20224 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20225 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20226 For example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20227
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20228 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20229 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20230 (mapcar '1+ '(2 4 6))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20231 @result{} (3 5 7)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20232 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20233 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20234
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20235 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20236 The function @code{1+} which adds one to its argument, is executed on
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20237 @emph{each} element of the list, and a new list is returned.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20238
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20239 Contrast this with @code{apply}, which applies its first argument to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20240 all the remaining.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20241 (@xref{Readying a Graph, , Readying a Graph}, for a explanation of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20242 @code{apply}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20243
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20244 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20245 In the definition of @code{one-fiftieth}, the first argument is the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20246 anonymous function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20247
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20248 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20249 (lambda (arg) (/ arg 50))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20250 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20251
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20252 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20253 and the second argument is @code{full-range}, which will be bound to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20254 @code{list-for-graph}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20255
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20256 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20257 The whole expression looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20258
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20259 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20260 (mapcar '(lambda (arg) (/ arg 50)) full-range))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20261 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20262
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20263 @xref{Mapping Functions, , Mapping Functions, elisp, The GNU Emacs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20264 Lisp Reference Manual}, for more about @code{mapcar}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20265
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20266 Using the @code{one-fiftieth} function, we can generate a list in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20267 which each element is one-fiftieth the size of the corresponding
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20268 element in @code{list-for-graph}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20269
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20270 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20271 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20272 (setq fiftieth-list-for-graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20273 (one-fiftieth list-for-graph))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20274 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20275 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20276
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20277 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20278 The resulting list looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20279
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20280 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20281 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20282 (10 20 19 15 11 9 6 5 4 3 3 2 2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20283 1 1 1 1 0 1 0 0 0 0 0 0 0 0 0 0 0 4)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20284 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20285 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20286
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20287 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20288 This, we are almost ready to print! (We also notice the loss of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20289 information: many of the higher ranges are 0, meaning that fewer than
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20290 50 defuns had that many words or symbols---but not necessarily meaning
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20291 that none had that many words or symbols.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20292
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20293 @node Another Bug, Final printed graph, mapcar, Print Whole Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20294 @appendixsubsec Another Bug @dots{} Most Insidious
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20295 @cindex Bug, most insidious type
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20296 @cindex Insidious type of bug
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20297
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20298 I said `almost ready to print'! Of course, there is a bug in the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20299 @code{print-graph} function @dots{} It has a @code{vertical-step}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20300 option, but not a @code{horizontal-step} option. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20301 @code{top-of-range} scale goes from 10 to 300 by tens. But the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20302 @code{print-graph} function will print only by ones.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20303
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20304 This is a classic example of what some consider the most insidious
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20305 type of bug, the bug of omission. This is not the kind of bug you can
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20306 find by studying the code, for it is not in the code; it is an omitted
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20307 feature. Your best actions are to try your program early and often;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20308 and try to arrange, as much as you can, to write code that is easy to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20309 understand and easy to change. Try to be aware, whenever you can,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20310 that whatever you have written, @emph{will} be rewritten, if not soon,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20311 eventually. A hard maxim to follow.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20312
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20313 It is the @code{print-X-axis-numbered-line} function that needs the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20314 work; and then the @code{print-X-axis} and the @code{print-graph}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20315 functions need to be adapted. Not much needs to be done; there is one
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20316 nicety: the numbers ought to line up under the tic marks. This takes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20317 a little thought.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20318
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20319 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20320 Here is the corrected @code{print-X-axis-numbered-line}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20321
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20322 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20323 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20324 (defun print-X-axis-numbered-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20325 (number-of-X-tics X-axis-leading-spaces
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20326 &optional horizontal-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20327 "Print line of X-axis numbers"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20328 (let ((number X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20329 (horizontal-step (or horizontal-step 1)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20330 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20331 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20332 (insert X-axis-leading-spaces)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20333 ;; @r{Delete extra leading spaces.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20334 (delete-char
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20335 (- (1-
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20336 (length (number-to-string horizontal-step)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20337 (insert (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20338 (make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20339 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20340 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20341 ;; @r{Insert white space.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20342 (- (* symbol-width
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20343 X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20344 (1-
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20345 (length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20346 (number-to-string horizontal-step)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20347 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20348 ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20349 (number-to-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20350 (* number horizontal-step))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20351 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20352 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20353 ;; @r{Insert remaining numbers.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20354 (setq number (+ number X-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20355 (while (> number-of-X-tics 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20356 (insert (X-axis-element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20357 (* number horizontal-step)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20358 (setq number (+ number X-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20359 (setq number-of-X-tics (1- number-of-X-tics)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20360 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20361 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20362
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20363 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20364 If you are reading this in Info, you can see the new versions of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20365 @code{print-X-axis} @code{print-graph} and evaluate them. If you are
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20366 reading this in a printed book, you can see the changed lines here
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20367 (the full text is too much to print).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20368
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20369 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20370 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20371 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20372 (defun print-X-axis (numbers-list horizontal-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20373 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20374 (print-X-axis-numbered-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20375 tic-number leading-spaces horizontal-step))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20376 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20377 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20378
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20379 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20380 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20381 (defun print-graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20382 (numbers-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20383 &optional vertical-step horizontal-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20384 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20385 (print-X-axis numbers-list horizontal-step))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20386 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20387 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20388 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20389
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20390 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20391 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20392 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20393 (defun print-X-axis (numbers-list horizontal-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20394 "Print X axis labels to length of NUMBERS-LIST.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20395 Optionally, HORIZONTAL-STEP, a positive integer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20396 specifies how much an X axis label increments for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20397 each column."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20398 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20399 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20400 ;; Value of symbol-width and full-Y-label-width
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20401 ;; are passed by `print-graph'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20402 (let* ((leading-spaces
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20403 (make-string full-Y-label-width ? ))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20404 ;; symbol-width @r{is provided by} graph-body-print
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20405 (tic-width (* symbol-width X-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20406 (X-length (length numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20407 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20408 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20409 (X-tic
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20410 (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20411 (make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20412 ;; @r{Make a string of blanks.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20413 (- (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20414 (length X-axis-tic-symbol))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20415 ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20416 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20417 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20418 ;; @r{Concatenate blanks with tic symbol.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20419 X-axis-tic-symbol))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20420 (tic-number
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20421 (if (zerop (% X-length tic-width))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20422 (/ X-length tic-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20423 (1+ (/ X-length tic-width)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20424 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20425
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20426 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20427 (print-X-axis-tic-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20428 tic-number leading-spaces X-tic)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20429 (insert "\n")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20430 (print-X-axis-numbered-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20431 tic-number leading-spaces horizontal-step)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20432 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20433 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20434
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20435 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20436 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20437 (defun print-graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20438 (numbers-list &optional vertical-step horizontal-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20439 "Print labelled bar graph of the NUMBERS-LIST.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20440 The numbers-list consists of the Y-axis values.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20441 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20442
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20443 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20444 Optionally, VERTICAL-STEP, a positive integer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20445 specifies how much a Y axis label increments for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20446 each line. For example, a step of 5 means that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20447 each row is five units.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20448 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20449
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20450 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20451 Optionally, HORIZONTAL-STEP, a positive integer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20452 specifies how much an X axis label increments for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20453 each column."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20454 (let* ((symbol-width (length graph-blank))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20455 ;; @code{height} @r{is both the largest number}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20456 ;; @r{and the number with the most digits.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20457 (height (apply 'max numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20458 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20459 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20460 (height-of-top-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20461 (if (zerop (% height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20462 height
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20463 ;; @r{else}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20464 (* (1+ (/ height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20465 Y-axis-label-spacing)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20466 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20467 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20468 (vertical-step (or vertical-step 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20469 (full-Y-label-width
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20470 (length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20471 (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20472 (number-to-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20473 (* height-of-top-line vertical-step))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20474 Y-axis-tic))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20475 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20476 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20477 (print-Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20478 height-of-top-line full-Y-label-width vertical-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20479 (graph-body-print
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20480 numbers-list height-of-top-line symbol-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20481 (print-X-axis numbers-list horizontal-step)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20482 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20483 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20484 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20485
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20486 @ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20487 Graphing Definitions Re-listed
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20488
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20489 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20490 Here are all the graphing definitions in their final form:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20491
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20492 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20493 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20494 (defvar top-of-ranges
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20495 '(10 20 30 40 50
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20496 60 70 80 90 100
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20497 110 120 130 140 150
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20498 160 170 180 190 200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20499 210 220 230 240 250)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20500 "List specifying ranges for `defuns-per-range'.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20501 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20502
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20503 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20504 (defvar graph-symbol "*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20505 "String used as symbol in graph, usually an asterisk.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20506 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20507
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20508 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20509 (defvar graph-blank " "
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20510 "String used as blank in graph, usually a blank space.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20511 graph-blank must be the same number of columns wide
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20512 as graph-symbol.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20513 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20514
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20515 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20516 (defvar Y-axis-tic " - "
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20517 "String that follows number in a Y axis label.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20518 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20519
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20520 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20521 (defvar Y-axis-label-spacing 5
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20522 "Number of lines from one Y axis label to next.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20523 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20524
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20525 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20526 (defvar X-axis-tic-symbol "|"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20527 "String to insert to point to a column in X axis.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20528 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20529
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20530 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20531 (defvar X-axis-label-spacing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20532 (if (boundp 'graph-blank)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20533 (* 5 (length graph-blank)) 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20534 "Number of units from one X axis label to next.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20535 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20536 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20537
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20538 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20539 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20540 (defun count-words-in-defun ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20541 "Return the number of words and symbols in a defun."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20542 (beginning-of-defun)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20543 (let ((count 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20544 (end (save-excursion (end-of-defun) (point))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20545 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20546
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20547 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20548 (while
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20549 (and (< (point) end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20550 (re-search-forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20551 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20552 end t))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20553 (setq count (1+ count)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20554 count))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20555 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20556 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20557
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20558 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20559 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20560 (defun lengths-list-file (filename)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20561 "Return list of definitions' lengths within FILE.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20562 The returned list is a list of numbers.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20563 Each number is the number of words or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20564 symbols in one function definition."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20565 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20566
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20567 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20568 (message "Working on `%s' ... " filename)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20569 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20570 (let ((buffer (find-file-noselect filename))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20571 (lengths-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20572 (set-buffer buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20573 (setq buffer-read-only t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20574 (widen)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20575 (goto-char (point-min))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20576 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20577
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20578 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20579 (while (re-search-forward "^(defun" nil t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20580 (setq lengths-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20581 (cons (count-words-in-defun) lengths-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20582 (kill-buffer buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20583 lengths-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20584 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20585 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20586
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20587 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20588 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20589 (defun lengths-list-many-files (list-of-files)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20590 "Return list of lengths of defuns in LIST-OF-FILES."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20591 (let (lengths-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20592 ;;; @r{true-or-false-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20593 (while list-of-files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20594 (setq lengths-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20595 (append
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20596 lengths-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20597 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20598 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20599 ;;; @r{Generate a lengths' list.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20600 (lengths-list-file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20601 (expand-file-name (car list-of-files)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20602 ;;; @r{Make files' list shorter.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20603 (setq list-of-files (cdr list-of-files)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20604 ;;; @r{Return final value of lengths' list.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20605 lengths-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20606 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20607 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20608
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20609 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20610 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20611 (defun defuns-per-range (sorted-lengths top-of-ranges)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20612 "SORTED-LENGTHS defuns in each TOP-OF-RANGES range."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20613 (let ((top-of-range (car top-of-ranges))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20614 (number-within-range 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20615 defuns-per-range-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20616 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20617
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20618 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20619 ;; @r{Outer loop.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20620 (while top-of-ranges
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20621
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20622 ;; @r{Inner loop.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20623 (while (and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20624 ;; @r{Need number for numeric test.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20625 (car sorted-lengths)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20626 (< (car sorted-lengths) top-of-range))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20627
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20628 ;; @r{Count number of definitions within current range.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20629 (setq number-within-range (1+ number-within-range))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20630 (setq sorted-lengths (cdr sorted-lengths)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20631 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20632
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20633 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20634 ;; @r{Exit inner loop but remain within outer loop.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20635
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20636 (setq defuns-per-range-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20637 (cons number-within-range defuns-per-range-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20638 (setq number-within-range 0) ; @r{Reset count to zero.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20639
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20640 ;; @r{Move to next range.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20641 (setq top-of-ranges (cdr top-of-ranges))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20642 ;; @r{Specify next top of range value.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20643 (setq top-of-range (car top-of-ranges)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20644 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20645
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20646 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20647 ;; @r{Exit outer loop and count the number of defuns larger than}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20648 ;; @r{ the largest top-of-range value.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20649 (setq defuns-per-range-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20650 (cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20651 (length sorted-lengths)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20652 defuns-per-range-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20653
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20654 ;; @r{Return a list of the number of definitions within each range,}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20655 ;; @r{ smallest to largest.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20656 (nreverse defuns-per-range-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20657 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20658 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20659
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20660 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20661 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20662 (defun column-of-graph (max-graph-height actual-height)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20663 "Return list of MAX-GRAPH-HEIGHT strings;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20664 ACTUAL-HEIGHT are graph-symbols.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20665 The graph-symbols are contiguous entries at the end
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20666 of the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20667 The list will be inserted as one column of a graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20668 The strings are either graph-blank or graph-symbol."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20669 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20670
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20671 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20672 (let ((insert-list nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20673 (number-of-top-blanks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20674 (- max-graph-height actual-height)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20675
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20676 ;; @r{Fill in @code{graph-symbols}.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20677 (while (> actual-height 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20678 (setq insert-list (cons graph-symbol insert-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20679 (setq actual-height (1- actual-height)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20680 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20681
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20682 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20683 ;; @r{Fill in @code{graph-blanks}.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20684 (while (> number-of-top-blanks 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20685 (setq insert-list (cons graph-blank insert-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20686 (setq number-of-top-blanks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20687 (1- number-of-top-blanks)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20688
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20689 ;; @r{Return whole list.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20690 insert-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20691 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20692 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20693
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20694 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20695 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20696 (defun Y-axis-element (number full-Y-label-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20697 "Construct a NUMBERed label element.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20698 A numbered element looks like this ` 5 - ',
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20699 and is padded as needed so all line up with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20700 the element for the largest number."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20701 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20702 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20703 (let* ((leading-spaces
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20704 (- full-Y-label-width
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20705 (length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20706 (concat (number-to-string number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20707 Y-axis-tic)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20708 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20709 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20710 (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20711 (make-string leading-spaces ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20712 (number-to-string number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20713 Y-axis-tic)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20714 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20715 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20716
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20717 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20718 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20719 (defun print-Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20720 (height full-Y-label-width &optional vertical-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20721 "Insert Y axis by HEIGHT and FULL-Y-LABEL-WIDTH.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20722 Height must be the maximum height of the graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20723 Full width is the width of the highest label element.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20724 Optionally, print according to VERTICAL-STEP."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20725 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20726 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20727 ;; Value of height and full-Y-label-width
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20728 ;; are passed by `print-graph'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20729 (let ((start (point)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20730 (insert-rectangle
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20731 (Y-axis-column height full-Y-label-width vertical-step))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20732 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20733 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20734 ;; @r{Place point ready for inserting graph.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20735 (goto-char start)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20736 ;; @r{Move point forward by value of} full-Y-label-width
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20737 (forward-char full-Y-label-width)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20738 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20739 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20740
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20741 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20742 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20743 (defun print-X-axis-tic-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20744 (number-of-X-tics X-axis-leading-spaces X-axis-tic-element)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20745 "Print tics for X axis."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20746 (insert X-axis-leading-spaces)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20747 (insert X-axis-tic-symbol) ; @r{Under first column.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20748 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20749 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20750 ;; @r{Insert second tic in the right spot.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20751 (insert (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20752 (make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20753 (- (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20754 ;; @r{Insert white space up to second tic symbol.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20755 (* 2 (length X-axis-tic-symbol)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20756 ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20757 X-axis-tic-symbol))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20758 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20759 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20760 ;; @r{Insert remaining tics.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20761 (while (> number-of-X-tics 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20762 (insert X-axis-tic-element)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20763 (setq number-of-X-tics (1- number-of-X-tics))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20764 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20765 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20766
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20767 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20768 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20769 (defun X-axis-element (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20770 "Construct a numbered X axis element."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20771 (let ((leading-spaces
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20772 (- (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20773 (length (number-to-string number)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20774 (concat (make-string leading-spaces ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20775 (number-to-string number))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20776 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20777 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20778
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20779 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20780 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20781 (defun graph-body-print (numbers-list height symbol-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20782 "Print a bar graph of the NUMBERS-LIST.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20783 The numbers-list consists of the Y-axis values.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20784 HEIGHT is maximum height of graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20785 SYMBOL-WIDTH is number of each column."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20786 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20787 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20788 (let (from-position)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20789 (while numbers-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20790 (setq from-position (point))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20791 (insert-rectangle
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20792 (column-of-graph height (car numbers-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20793 (goto-char from-position)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20794 (forward-char symbol-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20795 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20796 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20797 ;; @r{Draw graph column by column.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20798 (sit-for 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20799 (setq numbers-list (cdr numbers-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20800 ;; @r{Place point for X axis labels.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20801 (forward-line height)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20802 (insert "\n")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20803 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20804 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20805
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20806 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20807 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20808 (defun Y-axis-column
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20809 (height width-of-label &optional vertical-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20810 "Construct list of labels for Y axis.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20811 HEIGHT is maximum height of graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20812 WIDTH-OF-LABEL is maximum width of label.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20813 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20814 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20815 VERTICAL-STEP, an option, is a positive integer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20816 that specifies how much a Y axis label increments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20817 for each line. For example, a step of 5 means
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20818 that each line is five units of the graph."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20819 (let (Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20820 (number-per-line (or vertical-step 1)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20821 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20822 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20823 (while (> height 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20824 (if (zerop (% height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20825 ;; @r{Insert label.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20826 (setq Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20827 (cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20828 (Y-axis-element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20829 (* height number-per-line)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20830 width-of-label)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20831 Y-axis))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20832 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20833 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20834 ;; @r{Else, insert blanks.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20835 (setq Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20836 (cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20837 (make-string width-of-label ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20838 Y-axis)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20839 (setq height (1- height)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20840 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20841 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20842 ;; @r{Insert base line.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20843 (setq Y-axis (cons (Y-axis-element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20844 (or vertical-step 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20845 width-of-label)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20846 Y-axis))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20847 (nreverse Y-axis)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20848 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20849 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20850
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20851 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20852 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20853 (defun print-X-axis-numbered-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20854 (number-of-X-tics X-axis-leading-spaces
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20855 &optional horizontal-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20856 "Print line of X-axis numbers"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20857 (let ((number X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20858 (horizontal-step (or horizontal-step 1)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20859 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20860 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20861 (insert X-axis-leading-spaces)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20862 ;; line up number
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20863 (delete-char (- (1- (length (number-to-string horizontal-step)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20864 (insert (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20865 (make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20866 ;; @r{Insert white space up to next number.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20867 (- (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20868 (1- (length (number-to-string horizontal-step)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20869 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20870 ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20871 (number-to-string (* number horizontal-step))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20872 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20873 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20874 ;; @r{Insert remaining numbers.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20875 (setq number (+ number X-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20876 (while (> number-of-X-tics 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20877 (insert (X-axis-element (* number horizontal-step)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20878 (setq number (+ number X-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20879 (setq number-of-X-tics (1- number-of-X-tics)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20880 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20881 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20882
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20883 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20884 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20885 (defun print-X-axis (numbers-list horizontal-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20886 "Print X axis labels to length of NUMBERS-LIST.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20887 Optionally, HORIZONTAL-STEP, a positive integer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20888 specifies how much an X axis label increments for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20889 each column."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20890 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20891 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20892 ;; Value of symbol-width and full-Y-label-width
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20893 ;; are passed by `print-graph'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20894 (let* ((leading-spaces
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20895 (make-string full-Y-label-width ? ))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20896 ;; symbol-width @r{is provided by} graph-body-print
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20897 (tic-width (* symbol-width X-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20898 (X-length (length numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20899 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20900 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20901 (X-tic
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20902 (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20903 (make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20904 ;; @r{Make a string of blanks.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20905 (- (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20906 (length X-axis-tic-symbol))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20907 ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20908 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20909 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20910 ;; @r{Concatenate blanks with tic symbol.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20911 X-axis-tic-symbol))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20912 (tic-number
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20913 (if (zerop (% X-length tic-width))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20914 (/ X-length tic-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20915 (1+ (/ X-length tic-width)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20916 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20917
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20918 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20919 (print-X-axis-tic-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20920 tic-number leading-spaces X-tic)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20921 (insert "\n")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20922 (print-X-axis-numbered-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20923 tic-number leading-spaces horizontal-step)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20924 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20925 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20926
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20927 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20928 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20929 (defun one-fiftieth (full-range)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20930 "Return list, each number of which is 1/50th previous."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20931 (mapcar '(lambda (arg) (/ arg 50)) full-range))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20932 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20933 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20934
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20935 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20936 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20937 (defun print-graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20938 (numbers-list &optional vertical-step horizontal-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20939 "Print labelled bar graph of the NUMBERS-LIST.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20940 The numbers-list consists of the Y-axis values.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20941 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20942
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20943 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20944 Optionally, VERTICAL-STEP, a positive integer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20945 specifies how much a Y axis label increments for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20946 each line. For example, a step of 5 means that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20947 each row is five units.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20948 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20949
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20950 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20951 Optionally, HORIZONTAL-STEP, a positive integer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20952 specifies how much an X axis label increments for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20953 each column."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20954 (let* ((symbol-width (length graph-blank))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20955 ;; @code{height} @r{is both the largest number}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20956 ;; @r{and the number with the most digits.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20957 (height (apply 'max numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20958 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20959 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20960 (height-of-top-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20961 (if (zerop (% height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20962 height
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20963 ;; @r{else}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20964 (* (1+ (/ height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20965 Y-axis-label-spacing)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20966 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20967 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20968 (vertical-step (or vertical-step 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20969 (full-Y-label-width
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20970 (length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20971 (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20972 (number-to-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20973 (* height-of-top-line vertical-step))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20974 Y-axis-tic))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20975 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20976 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20977
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20978 (print-Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20979 height-of-top-line full-Y-label-width vertical-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20980 (graph-body-print
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20981 numbers-list height-of-top-line symbol-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20982 (print-X-axis numbers-list horizontal-step)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20983 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20984 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20985 @end ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20986
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20987 @page
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20988 @node Final printed graph, , Another Bug, Print Whole Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20989 @appendixsubsec The Printed Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20990
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20991 When made and installed, you can call the @code{print-graph} command
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20992 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20993
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20994 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20995 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20996 (print-graph fiftieth-list-for-graph 50 10)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20997 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20998 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20999
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21000 Here is the graph:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21001
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21002 @sp 2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21003
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21004 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21005 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21006 1000 - *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21007 **
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21008 **
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21009 **
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21010 **
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21011 750 - ***
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21012 ***
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21013 ***
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21014 ***
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21015 ****
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21016 500 - *****
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21017 ******
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21018 ******
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21019 ******
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21020 *******
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21021 250 - ********
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21022 ********* *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21023 *********** *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21024 ************* *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21025 50 - ***************** * *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21026 | | | | | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21027 10 50 100 150 200 250 300 350
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21028 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21029 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21030
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21031 @sp 2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21032
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21033 The largest group of functions contain 10 -- 19 words and symbols each.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21034
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21035 @node GNU Free Documentation License, Index, Full Graph, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21036 @appendix GNU Free Documentation License
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21037
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21038 @cindex FDL, GNU Free Documentation License
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21039 @center Version 1.1, March 2000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21040
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21041 @display
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21042 Copyright @copyright{} 2000 Free Software Foundation, Inc.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21043 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21044
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21045 Everyone is permitted to copy and distribute verbatim copies
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21046 of this license document, but changing it is not allowed.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21047 @end display
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21048
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21049 @enumerate 0
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21050 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21051 PREAMBLE
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21052
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21053 The purpose of this License is to make a manual, textbook, or other
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21054 written document @dfn{free} in the sense of freedom: to assure everyone
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21055 the effective freedom to copy and redistribute it, with or without
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21056 modifying it, either commercially or noncommercially. Secondarily,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21057 this License preserves for the author and publisher a way to get
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21058 credit for their work, while not being considered responsible for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21059 modifications made by others.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21060
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21061 This License is a kind of ``copyleft'', which means that derivative
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21062 works of the document must themselves be free in the same sense. It
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21063 complements the GNU General Public License, which is a copyleft
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21064 license designed for free software.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21065
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21066 We have designed this License in order to use it for manuals for free
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21067 software, because free software needs free documentation: a free
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21068 program should come with manuals providing the same freedoms that the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21069 software does. But this License is not limited to software manuals;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21070 it can be used for any textual work, regardless of subject matter or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21071 whether it is published as a printed book. We recommend this License
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21072 principally for works whose purpose is instruction or reference.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21073
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21074 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21075 APPLICABILITY AND DEFINITIONS
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21076
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21077 This License applies to any manual or other work that contains a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21078 notice placed by the copyright holder saying it can be distributed
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21079 under the terms of this License. The ``Document'', below, refers to any
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21080 such manual or work. Any member of the public is a licensee, and is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21081 addressed as ``you''.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21082
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21083 A ``Modified Version'' of the Document means any work containing the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21084 Document or a portion of it, either copied verbatim, or with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21085 modifications and/or translated into another language.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21086
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21087 A ``Secondary Section'' is a named appendix or a front-matter section of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21088 the Document that deals exclusively with the relationship of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21089 publishers or authors of the Document to the Document's overall subject
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21090 (or to related matters) and contains nothing that could fall directly
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21091 within that overall subject. (For example, if the Document is in part a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21092 textbook of mathematics, a Secondary Section may not explain any
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21093 mathematics.) The relationship could be a matter of historical
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21094 connection with the subject or with related matters, or of legal,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21095 commercial, philosophical, ethical or political position regarding
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21096 them.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21097
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21098 The ``Invariant Sections'' are certain Secondary Sections whose titles
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21099 are designated, as being those of Invariant Sections, in the notice
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21100 that says that the Document is released under this License.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21101
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21102 The ``Cover Texts'' are certain short passages of text that are listed,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21103 as Front-Cover Texts or Back-Cover Texts, in the notice that says that
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21104 the Document is released under this License.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21105
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21106 A ``Transparent'' copy of the Document means a machine-readable copy,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21107 represented in a format whose specification is available to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21108 general public, whose contents can be viewed and edited directly and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21109 straightforwardly with generic text editors or (for images composed of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21110 pixels) generic paint programs or (for drawings) some widely available
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21111 drawing editor, and that is suitable for input to text formatters or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21112 for automatic translation to a variety of formats suitable for input
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21113 to text formatters. A copy made in an otherwise Transparent file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21114 format whose markup has been designed to thwart or discourage
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21115 subsequent modification by readers is not Transparent. A copy that is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21116 not ``Transparent'' is called ``Opaque''.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21117
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21118 Examples of suitable formats for Transparent copies include plain
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21119 @sc{ascii} without markup, Texinfo input format, La@TeX{} input format,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21120 @acronym{SGML} or @acronym{XML} using a publicly available
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21121 @acronym{DTD}, and standard-conforming simple @acronym{HTML} designed
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21122 for human modification. Opaque formats include PostScript,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21123 @acronym{PDF}, proprietary formats that can be read and edited only by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21124 proprietary word processors, @acronym{SGML} or @acronym{XML} for which
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21125 the @acronym{DTD} and/or processing tools are not generally available,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21126 and the machine-generated @acronym{HTML} produced by some word
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21127 processors for output purposes only.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21128
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21129 The ``Title Page'' means, for a printed book, the title page itself,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21130 plus such following pages as are needed to hold, legibly, the material
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21131 this License requires to appear in the title page. For works in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21132 formats which do not have any title page as such, ``Title Page'' means
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21133 the text near the most prominent appearance of the work's title,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21134 preceding the beginning of the body of the text.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21135
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21136 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21137 VERBATIM COPYING
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21138
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21139 You may copy and distribute the Document in any medium, either
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21140 commercially or noncommercially, provided that this License, the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21141 copyright notices, and the license notice saying this License applies
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21142 to the Document are reproduced in all copies, and that you add no other
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21143 conditions whatsoever to those of this License. You may not use
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21144 technical measures to obstruct or control the reading or further
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21145 copying of the copies you make or distribute. However, you may accept
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21146 compensation in exchange for copies. If you distribute a large enough
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21147 number of copies you must also follow the conditions in section 3.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21148
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21149 You may also lend copies, under the same conditions stated above, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21150 you may publicly display copies.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21151
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21152 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21153 COPYING IN QUANTITY
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21154
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21155 If you publish printed copies of the Document numbering more than 100,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21156 and the Document's license notice requires Cover Texts, you must enclose
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21157 the copies in covers that carry, clearly and legibly, all these Cover
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21158 Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21159 the back cover. Both covers must also clearly and legibly identify
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21160 you as the publisher of these copies. The front cover must present
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21161 the full title with all words of the title equally prominent and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21162 visible. You may add other material on the covers in addition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21163 Copying with changes limited to the covers, as long as they preserve
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21164 the title of the Document and satisfy these conditions, can be treated
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21165 as verbatim copying in other respects.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21166
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21167 If the required texts for either cover are too voluminous to fit
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21168 legibly, you should put the first ones listed (as many as fit
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21169 reasonably) on the actual cover, and continue the rest onto adjacent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21170 pages.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21171
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21172 If you publish or distribute Opaque copies of the Document numbering
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21173 more than 100, you must either include a machine-readable Transparent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21174 copy along with each Opaque copy, or state in or with each Opaque copy
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21175 a publicly-accessible computer-network location containing a complete
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21176 Transparent copy of the Document, free of added material, which the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21177 general network-using public has access to download anonymously at no
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21178 charge using public-standard network protocols. If you use the latter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21179 option, you must take reasonably prudent steps, when you begin
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21180 distribution of Opaque copies in quantity, to ensure that this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21181 Transparent copy will remain thus accessible at the stated location
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21182 until at least one year after the last time you distribute an Opaque
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21183 copy (directly or through your agents or retailers) of that edition to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21184 the public.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21185
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21186 It is requested, but not required, that you contact the authors of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21187 Document well before redistributing any large number of copies, to give
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21188 them a chance to provide you with an updated version of the Document.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21189
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21190 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21191 MODIFICATIONS
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21192
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21193 You may copy and distribute a Modified Version of the Document under
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21194 the conditions of sections 2 and 3 above, provided that you release
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21195 the Modified Version under precisely this License, with the Modified
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21196 Version filling the role of the Document, thus licensing distribution
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21197 and modification of the Modified Version to whoever possesses a copy
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21198 of it. In addition, you must do these things in the Modified Version:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21199
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21200 @enumerate A
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21201 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21202 Use in the Title Page (and on the covers, if any) a title distinct
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21203 from that of the Document, and from those of previous versions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21204 (which should, if there were any, be listed in the History section
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21205 of the Document). You may use the same title as a previous version
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21206 if the original publisher of that version gives permission.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21207
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21208 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21209 List on the Title Page, as authors, one or more persons or entities
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21210 responsible for authorship of the modifications in the Modified
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21211 Version, together with at least five of the principal authors of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21212 Document (all of its principal authors, if it has less than five).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21213
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21214 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21215 State on the Title page the name of the publisher of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21216 Modified Version, as the publisher.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21217
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21218 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21219 Preserve all the copyright notices of the Document.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21220
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21221 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21222 Add an appropriate copyright notice for your modifications
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21223 adjacent to the other copyright notices.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21224
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21225 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21226 Include, immediately after the copyright notices, a license notice
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21227 giving the public permission to use the Modified Version under the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21228 terms of this License, in the form shown in the Addendum below.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21229
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21230 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21231 Preserve in that license notice the full lists of Invariant Sections
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21232 and required Cover Texts given in the Document's license notice.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21233
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21234 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21235 Include an unaltered copy of this License.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21236
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21237 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21238 Preserve the section entitled ``History'', and its title, and add to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21239 it an item stating at least the title, year, new authors, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21240 publisher of the Modified Version as given on the Title Page. If
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21241 there is no section entitled ``History'' in the Document, create one
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21242 stating the title, year, authors, and publisher of the Document as
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21243 given on its Title Page, then add an item describing the Modified
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21244 Version as stated in the previous sentence.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21245
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21246 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21247 Preserve the network location, if any, given in the Document for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21248 public access to a Transparent copy of the Document, and likewise
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21249 the network locations given in the Document for previous versions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21250 it was based on. These may be placed in the ``History'' section.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21251 You may omit a network location for a work that was published at
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21252 least four years before the Document itself, or if the original
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21253 publisher of the version it refers to gives permission.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21254
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21255 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21256 In any section entitled ``Acknowledgments'' or ``Dedications'',
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21257 preserve the section's title, and preserve in the section all the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21258 substance and tone of each of the contributor acknowledgments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21259 and/or dedications given therein.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21260
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21261 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21262 Preserve all the Invariant Sections of the Document,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21263 unaltered in their text and in their titles. Section numbers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21264 or the equivalent are not considered part of the section titles.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21265
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21266 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21267 Delete any section entitled ``Endorsements''. Such a section
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21268 may not be included in the Modified Version.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21269
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21270 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21271 Do not retitle any existing section as ``Endorsements''
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21272 or to conflict in title with any Invariant Section.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21273 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21274
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21275 If the Modified Version includes new front-matter sections or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21276 appendices that qualify as Secondary Sections and contain no material
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21277 copied from the Document, you may at your option designate some or all
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21278 of these sections as invariant. To do this, add their titles to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21279 list of Invariant Sections in the Modified Version's license notice.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21280 These titles must be distinct from any other section titles.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21281
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21282 You may add a section entitled ``Endorsements'', provided it contains
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21283 nothing but endorsements of your Modified Version by various
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21284 parties---for example, statements of peer review or that the text has
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21285 been approved by an organization as the authoritative definition of a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21286 standard.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21287
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21288 You may add a passage of up to five words as a Front-Cover Text, and a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21289 passage of up to 25 words as a Back-Cover Text, to the end of the list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21290 of Cover Texts in the Modified Version. Only one passage of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21291 Front-Cover Text and one of Back-Cover Text may be added by (or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21292 through arrangements made by) any one entity. If the Document already
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21293 includes a cover text for the same cover, previously added by you or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21294 by arrangement made by the same entity you are acting on behalf of,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21295 you may not add another; but you may replace the old one, on explicit
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21296 permission from the previous publisher that added the old one.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21297
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21298 The author(s) and publisher(s) of the Document do not by this License
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21299 give permission to use their names for publicity for or to assert or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21300 imply endorsement of any Modified Version.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21301
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21302 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21303 COMBINING DOCUMENTS
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21304
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21305 You may combine the Document with other documents released under this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21306 License, under the terms defined in section 4 above for modified
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21307 versions, provided that you include in the combination all of the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21308 Invariant Sections of all of the original documents, unmodified, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21309 list them all as Invariant Sections of your combined work in its
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21310 license notice.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21311
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21312 The combined work need only contain one copy of this License, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21313 multiple identical Invariant Sections may be replaced with a single
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21314 copy. If there are multiple Invariant Sections with the same name but
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21315 different contents, make the title of each such section unique by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21316 adding at the end of it, in parentheses, the name of the original
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21317 author or publisher of that section if known, or else a unique number.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21318 Make the same adjustment to the section titles in the list of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21319 Invariant Sections in the license notice of the combined work.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21320
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21321 In the combination, you must combine any sections entitled ``History''
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21322 in the various original documents, forming one section entitled
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21323 ``History''; likewise combine any sections entitled ``Acknowledgments'',
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21324 and any sections entitled ``Dedications''. You must delete all sections
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21325 entitled ``Endorsements.''
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21326
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21327 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21328 COLLECTIONS OF DOCUMENTS
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21329
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21330 You may make a collection consisting of the Document and other documents
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21331 released under this License, and replace the individual copies of this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21332 License in the various documents with a single copy that is included in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21333 the collection, provided that you follow the rules of this License for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21334 verbatim copying of each of the documents in all other respects.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21335
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21336 You may extract a single document from such a collection, and distribute
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21337 it individually under this License, provided you insert a copy of this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21338 License into the extracted document, and follow this License in all
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21339 other respects regarding verbatim copying of that document.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21340
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21341 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21342 AGGREGATION WITH INDEPENDENT WORKS
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21343
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21344 A compilation of the Document or its derivatives with other separate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21345 and independent documents or works, in or on a volume of a storage or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21346 distribution medium, does not as a whole count as a Modified Version
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21347 of the Document, provided no compilation copyright is claimed for the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21348 compilation. Such a compilation is called an ``aggregate'', and this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21349 License does not apply to the other self-contained works thus compiled
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21350 with the Document, on account of their being thus compiled, if they
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21351 are not themselves derivative works of the Document.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21352
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21353 If the Cover Text requirement of section 3 is applicable to these
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21354 copies of the Document, then if the Document is less than one quarter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21355 of the entire aggregate, the Document's Cover Texts may be placed on
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21356 covers that surround only the Document within the aggregate.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21357 Otherwise they must appear on covers around the whole aggregate.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21358
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21359 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21360 TRANSLATION
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21361
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21362 Translation is considered a kind of modification, so you may
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21363 distribute translations of the Document under the terms of section 4.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21364 Replacing Invariant Sections with translations requires special
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21365 permission from their copyright holders, but you may include
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21366 translations of some or all Invariant Sections in addition to the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21367 original versions of these Invariant Sections. You may include a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21368 translation of this License provided that you also include the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21369 original English version of this License. In case of a disagreement
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21370 between the translation and the original English version of this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21371 License, the original English version will prevail.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21372
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21373 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21374 TERMINATION
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21375
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21376 You may not copy, modify, sublicense, or distribute the Document except
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21377 as expressly provided for under this License. Any other attempt to
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21378 copy, modify, sublicense or distribute the Document is void, and will
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21379 automatically terminate your rights under this License. However,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21380 parties who have received copies, or rights, from you under this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21381 License will not have their licenses terminated so long as such
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21382 parties remain in full compliance.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21383
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21384 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21385 FUTURE REVISIONS OF THIS LICENSE
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21386
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21387 The Free Software Foundation may publish new, revised versions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21388 of the GNU Free Documentation License from time to time. Such new
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21389 versions will be similar in spirit to the present version, but may
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21390 differ in detail to address new problems or concerns. See
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21391 @uref{http://www.gnu.org/copyleft/}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21392
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21393 Each version of the License is given a distinguishing version number.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21394 If the Document specifies that a particular numbered version of this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21395 License ``or any later version'' applies to it, you have the option of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21396 following the terms and conditions either of that specified version or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21397 of any later version that has been published (not as a draft) by the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21398 Free Software Foundation. If the Document does not specify a version
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21399 number of this License, you may choose any version ever published (not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21400 as a draft) by the Free Software Foundation.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21401 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21402
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21403 @node Index, About the Author, GNU Free Documentation License, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21404 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21405 @unnumbered Index
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21406
41670
b4c633081255 (Index): @ignore extraneous text.
Eli Zaretskii <eliz@gnu.org>
parents: 41499
diff changeset
21407 @ignore
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21408 MENU ENTRY: NODE NAME.
41670
b4c633081255 (Index): @ignore extraneous text.
Eli Zaretskii <eliz@gnu.org>
parents: 41499
diff changeset
21409 @end ignore
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21410
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21411 @printindex cp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21412
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21413 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21414 @c Place biographical information on right-hand (verso) page
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21415
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21416 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21417 \ifodd\pageno
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21418 \par\vfill\supereject
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21419 \global\evenheadline={\hfil} \global\evenfootline={\hfil}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21420 \global\oddheadline={\hfil} \global\oddfootline={\hfil}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21421 \page\hbox{}\page
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21422 \else
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21423 \par\vfill\supereject
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21424 \par\vfill\supereject
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21425 \global\evenheadline={\hfil} \global\evenfootline={\hfil}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21426 \global\oddheadline={\hfil} \global\oddfootline={\hfil}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21427 \page\hbox{}\page
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21428 \page\hbox{}\page
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21429 \fi
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21430 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21431
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21432 @page
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21433 @w{ }
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21434
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21435 @c ================ Biographical information ================
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21436
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21437 @w{ }
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21438 @sp 8
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21439 @center About the Author
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21440 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21441 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21442
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21443 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21444 @node About the Author, , Index, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21445 @unnumbered About the Author
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21446 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21447
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21448 @quotation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21449 Robert J. Chassell has worked with GNU Emacs since 1985. He writes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21450 and edits, teaches Emacs and Emacs Lisp, and speaks throughout the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21451 world on software freedom. Chassell was a founding Director and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21452 Treasurer of the Free Software Foundation, Inc. He is co-author of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21453 the @cite{Texinfo} manual, and has edited more than a dozen other
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21454 books. He graduated from Cambridge University, in England. He has an
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21455 abiding interest in social and economic history and flies his own
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21456 airplane.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21457 @end quotation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21458
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21459 @page
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21460 @w{ }
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21461
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21462 @c Prevent page number on blank verso, so eject it first.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21463 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21464 \par\vfill\supereject
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21465 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21466
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21467 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21468 @headings off
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21469 @evenheading @thispage @| @| @thistitle
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21470 @oddheading @| @| @thispage
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21471 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21472
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21473 @bye