annotate lispintro/emacs-lisp-intro.texi @ 43079:a202d9fb56eb

(quail-help): Don't call help-setup-xref.
author Richard M. Stallman <rms@gnu.org>
date Sun, 03 Feb 2002 10:33:01 +0000
parents c0f9dbfc8232
children 438494390a90
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
42562
fb149efd0c72 Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents: 42506
diff changeset
13 @c set for smallbook, which works for all sizes
41499
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
42562
fb149efd0c72 Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents: 42506
diff changeset
24 @set edition-number 2.05
fb149efd0c72 Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents: 42506
diff changeset
25 @set update-date 2001 Jan 5
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
42562
fb149efd0c72 Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents: 42506
diff changeset
234 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1997, 2001, 2002 Free Software Foundation, Inc.
41421
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
42621
33aa22b1c9c0 Remove Preface from the `Invariant Section' listing of the License,
Robert J. Chassell <bob@rattlesnake.com>
parents: 42562
diff changeset
238 any later version published by the Free Software Foundation; there
33aa22b1c9c0 Remove Preface from the `Invariant Section' listing of the License,
Robert J. Chassell <bob@rattlesnake.com>
parents: 42562
diff changeset
239 being no Invariant Section, with the Front-Cover Texts being ``A GNU
33aa22b1c9c0 Remove Preface from the `Invariant Section' listing of the License,
Robert J. Chassell <bob@rattlesnake.com>
parents: 42562
diff changeset
240 Manual'', and with the Back-Cover Texts as in (a) below. A copy of
33aa22b1c9c0 Remove Preface from the `Invariant Section' listing of the License,
Robert J. Chassell <bob@rattlesnake.com>
parents: 42562
diff changeset
241 the license is included in the section entitled ``GNU Free
42562
fb149efd0c72 Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents: 42506
diff changeset
242 Documentation License''.
fb149efd0c72 Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents: 42506
diff changeset
243
fb149efd0c72 Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents: 42506
diff changeset
244 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and
fb149efd0c72 Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents: 42506
diff changeset
245 modify this GNU Manual, like GNU software. Copies published by the
fb149efd0c72 Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents: 42506
diff changeset
246 Free Software Foundation raise funds for GNU development.''
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
247 @end ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
248
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
249 @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
250 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
251 {\begingroup%
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
252 \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
253 \endgroup}%
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
254 {\begingroup\hbox{}\vskip 0.25in \chaprm%
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
255 \centerline{Programming in Emacs Lisp}%
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
256 \endgroup\page\hbox{}\page}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
257 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
258
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
259 @titlepage
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
260 @sp 6
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
261 @center @titlefont{An Introduction to}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
262 @sp 2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
263 @center @titlefont{Programming in Emacs Lisp}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
264 @sp 2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
265 @center Second Edition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
266 @sp 4
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
267 @center by Robert J. Chassell
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
268
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
269 @page
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
270 @vskip 0pt plus 1filll
42562
fb149efd0c72 Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents: 42506
diff changeset
271 Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1997, 2001, 2002 Free Software Foundation, Inc.
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
272 @sp 2
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 Published by the Free Software Foundation, Inc.@*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
275 59 Temple Place, Suite 330@*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
276 Boston, MA 02111-1307 USA@*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
277
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
278 Edition @value{edition-number}, @value{update-date}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
279
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
280 @c Printed copies are available for $20 each.@*
42633
c0f9dbfc8232 Nitpicking change of format from ISBN-1882114-43-4 to ISBN 1-882114-43-4
Robert J. Chassell <bob@rattlesnake.com>
parents: 42632
diff changeset
281 ISBN 1-882114-43-4
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
282
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
283 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
284 under the terms of the GNU Free Documentation License, Version 1.1 or
42621
33aa22b1c9c0 Remove Preface from the `Invariant Section' listing of the License,
Robert J. Chassell <bob@rattlesnake.com>
parents: 42562
diff changeset
285 any later version published by the Free Software Foundation; there
33aa22b1c9c0 Remove Preface from the `Invariant Section' listing of the License,
Robert J. Chassell <bob@rattlesnake.com>
parents: 42562
diff changeset
286 being no Invariant Section, with the Front-Cover Texts being ``A GNU
33aa22b1c9c0 Remove Preface from the `Invariant Section' listing of the License,
Robert J. Chassell <bob@rattlesnake.com>
parents: 42562
diff changeset
287 Manual'', and with the Back-Cover Texts as in (a) below. A copy of
33aa22b1c9c0 Remove Preface from the `Invariant Section' listing of the License,
Robert J. Chassell <bob@rattlesnake.com>
parents: 42562
diff changeset
288 the license is included in the section entitled ``GNU Free
42562
fb149efd0c72 Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents: 42506
diff changeset
289 Documentation License''.
fb149efd0c72 Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents: 42506
diff changeset
290
fb149efd0c72 Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents: 42506
diff changeset
291 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and
fb149efd0c72 Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents: 42506
diff changeset
292 modify this GNU Manual, like GNU software. Copies published by the
fb149efd0c72 Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents: 42506
diff changeset
293 Free Software Foundation raise funds for GNU development.''
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
294 @end titlepage
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
295
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
296 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
297 @headings off
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
298 @evenheading @thispage @| @| @thischapter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
299 @oddheading @thissection @| @| @thispage
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
300 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
301
41499
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
302 @ifnothtml
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 @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
305 @ifset largebook
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
306 @tex
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
307 \global\parskip 2pt plus 1pt
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
308 \global\advance\baselineskip by -1pt
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
309 @end tex
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
310 @end ifset
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
311
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
312 @shortcontents
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
313 @contents
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
314
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
315 @ifset largebook
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
316 @tex
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
317 \global\parskip 6pt plus 1pt
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
318 \global\advance\baselineskip by 1pt
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
319 @end tex
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
320 @end ifset
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
321
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
322 @end ifnothtml
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
323
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
324 @c >>>> Set pageno appropriately <<<<
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
325
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
326 @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
327 @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
328 @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
329
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
330 @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
331 @ifset largebook
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
332 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
333 @pageno = -9
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
334 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
335 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
336
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
337 @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
338 @ifclear largebook
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
339 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
340 @pageno = -11
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
341 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
342 @end ifclear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
343
41499
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
344 @ifnottex
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
345 @node Top, Preface, (dir), (dir)
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
346 @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
347
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
348 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
349 people who are not programmers.
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
350
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
351 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
352 every node in every chapter.
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
353 @end ifnottex
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
354
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
355 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
356 * Preface:: What to look for.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
357 * List Processing:: What is Lisp?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
358 * Practicing Evaluation:: Running several programs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
359 * Writing Defuns:: How to write function definitions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
360 * 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
361 * 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
362 * 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
363 a region.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
364 * car cdr & cons:: Fundamental functions in Lisp.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
365 * 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
366 * 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
367 * Yanking:: Pasting stored text.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
368 * Loops & Recursion:: How to repeat a process.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
369 * Regexp Search:: Regular expression searches.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
370 * 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
371 * 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
372 * 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
373 * 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
374 * 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
375 * Conclusion:: Now you have the basics.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
376 * 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
377 * 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
378 * 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
379 * GNU Free Documentation License::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
380 * Index::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
381 * About the Author::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
382
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
383 @detailmenu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
384 --- The Detailed Node Listing ---
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
385
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
386 Preface
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
387
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
388 * Why:: Why learn Emacs Lisp?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
389 * 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
390 * 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
391 * Lisp History::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
392 * 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
393 * Thank You::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
394
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
395 List Processing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
396
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
397 * Lisp Lists:: What are lists?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
398 * 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
399 * Making Errors:: Generating an error message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
400 * 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
401 * Lisp Interpreter:: What the Lisp interpreter does.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
402 * Evaluation:: Running a program.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
403 * Variables:: Returning a value from a variable.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
404 * Arguments:: Passing information to a function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
405 * 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
406 * Summary:: The major points.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
407 * Error Message Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
408
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
409 Lisp Lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
410
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
411 * 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
412 * Lisp Atoms:: Elemental entities.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
413 * 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
414 * 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
415
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
416 The Lisp Interpreter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
417
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
418 * Complications:: Variables, Special forms, Lists within.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
419 * Byte Compiling:: Specially processing code for speed.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
420
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
421 Evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
422
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
423 * Evaluating Inner Lists:: Lists within lists...
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
424
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
425 Variables
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
426
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
427 * fill-column Example::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
428 * 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
429 without a function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
430 * 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
431
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
432 Arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
433
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
434 * 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
435 * 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
436 of a variable or list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
437 * 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
438 variable number of arguments.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
439 * 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
440 to a function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
441 * message:: A useful function for sending messages.
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 Setting the Value of a Variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
444
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
445 * Using set:: Setting values.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
446 * Using setq:: Setting a quoted value.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
447 * Counting:: Using @code{setq} to count.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
448
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
449 Practicing Evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
450
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
451 * 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
452 causes evaluation.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
453 * Buffer Names:: Buffers and files are different.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
454 * 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
455 * 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
456 * 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
457 the buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
458 * Evaluation Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
459
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
460 How To Write Function Definitions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
461
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
462 * Primitive Functions::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
463 * defun:: The @code{defun} special form.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
464 * Install:: Install a function definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
465 * Interactive:: Making a function interactive.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
466 * Interactive Options:: Different options for @code{interactive}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
467 * Permanent Installation:: Installing code permanently.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
468 * let:: Creating and initializing local variables.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
469 * if:: What if?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
470 * else:: If--then--else expressions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
471 * 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
472 * 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
473 * Review::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
474 * defun Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
475
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
476 Install a Function Definition
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 * Effect of installation::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
479 * 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
480
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
481 Make a Function Interactive
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
482
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
483 * Interactive multiply-by-seven:: An overview.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
484 * 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
485
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
486 @code{let}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
487
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
488 * Prevent confusion::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
489 * Parts of let Expression::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
490 * Sample let Expression::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
491 * Uninitialized let Variables::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
492
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
493 The @code{if} Special Form
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
494
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
495 * if in more detail::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
496 * 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
497
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
498 Truth and Falsehood in Emacs Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
499
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
500 * nil explained:: @code{nil} has two meanings.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
501
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
502 @code{save-excursion}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
503
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
504 * 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
505 * Template for save-excursion::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
506
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
507 A Few Buffer--Related Functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
508
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
509 * Finding More:: How to find more information.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
510 * 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
511 @code{point-min}, and @code{push-mark}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
512 * 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
513 * 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
514 @code{insert-buffer-substring}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
515 * Buffer Related Review:: Review.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
516 * Buffer Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
517
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
518 The Definition of @code{mark-whole-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
519
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
520 * mark-whole-buffer overview::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
521 * 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
522
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
523 The Definition of @code{append-to-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
524
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
525 * append-to-buffer overview::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
526 * append interactive:: A two part interactive expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
527 * 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
528 * 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
529
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
530 A Few More Complex Functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
531
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
532 * 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
533 * 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
534 * beginning-of-buffer:: Shows @code{goto-char},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
535 @code{point-min}, and @code{push-mark}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
536 * Second Buffer Related Review::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
537 * optional Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
538
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
539 The Definition of @code{insert-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
540
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
541 * insert-buffer code::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
542 * 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
543 * 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
544 * 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
545 * 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
546 * Insert let:: Two @code{save-excursion} expressions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
547
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
548 The Interactive Expression in @code{insert-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
549
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
550 * 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
551 * 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
552
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
553 Complete Definition of @code{beginning-of-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
554
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
555 * Optional Arguments::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
556 * 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
557 * beginning-of-buffer complete::
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 @code{beginning-of-buffer} with an Argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
560
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
561 * Disentangle beginning-of-buffer::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
562 * Large buffer case::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
563 * Small buffer case::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
564
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
565 Narrowing and Widening
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
566
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
567 * Narrowing advantages:: The advantages of narrowing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
568 * 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
569 * 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
570 * narrow Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
571
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
572 @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
573
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
574 * 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
575 * 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
576 * cons:: Constructing a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
577 * nthcdr:: Calling @code{cdr} repeatedly.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
578 * nth::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
579 * 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
580 * setcdr:: Changing the rest of a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
581 * cons Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
582
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
583 @code{cons}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
584
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
585 * Build a list::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
586 * 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
587
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
588 Cutting and Storing Text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
589
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
590 * 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
591 * 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
592 * 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
593 * 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
594 * 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
595 * 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
596 * cons & search-fwd Review::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
597 * search Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
598
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
599 @code{zap-to-char}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
600
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
601 * Complete zap-to-char:: The complete implementation.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
602 * 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
603 * zap-to-char body:: A short overview.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
604 * 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
605 * progn:: The @code{progn} special form.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
606 * 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
607
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
608 @code{kill-region}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
609
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
610 * Complete kill-region:: The function definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
611 * condition-case:: Dealing with a problem.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
612 * delete-and-extract-region:: Doing the work.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
613
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
614 Initializing a Variable with @code{defvar}
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 * See variable current value::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
617 * defvar and asterisk:: An old-time convention.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
618
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
619 @code{copy-region-as-kill}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
620
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
621 * 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
622 * 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
623
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
624 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
625
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
626 * last-command & this-command::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
627 * kill-append function::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
628 * kill-new function::
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 How Lists are Implemented
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
631
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
632 * Lists diagrammed::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
633 * Symbols as Chest:: Exploring a powerful metaphor.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
634 * List Exercise::
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 Yanking Text Back
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
637
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
638 * 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
639 * 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
640 * yank nthcdr Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
641
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
642 Loops and Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
643
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
644 * 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
645 * dolist dotimes::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
646 * Recursion:: Causing a function to call itself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
647 * Looping exercise::
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 @code{while}
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 * 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
652 * 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
653 * 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
654 * 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
655 * 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
656
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
657 A Loop with an Incrementing Counter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
658
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
659 * Incrementing Example:: Counting pebbles in a triangle.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
660 * 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
661 * 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
662
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
663 Loop with a Decrementing Counter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
664
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
665 * Decrementing Example:: More pebbles on the beach.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
666 * 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
667 * 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
668
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
669 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
670
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
671 * dolist::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
672 * dotimes::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
673
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
674 Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
675
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
676 * Building Robots:: Same model, different serial number ...
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
677 * Recursive Definition Parts:: Walk until you stop ...
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
678 * 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
679 * Recursive triangle function::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
680 * Recursion with cond::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
681 * Recursive Patterns:: Often used templates.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
682 * No Deferment:: Don't store up work ...
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
683 * No deferment solution::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
684
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
685 Recursion in Place of a Counter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
686
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
687 * Recursive Example arg of 1 or 2::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
688 * Recursive Example arg of 3 or 4::
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 Recursive Patterns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
691
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
692 * Every::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
693 * Accumulate::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
694 * Keep::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
695
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
696 Regular Expression Searches
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 * 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
699 * 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
700 * 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
701 * forward-paragraph:: A somewhat complex example.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
702 * 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
703 * Regexp Review::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
704 * re-search Exercises::
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 @code{forward-sentence}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
707
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
708 * Complete forward-sentence::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
709 * 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
710 * 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
711
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
712 @code{forward-paragraph}: a Goldmine of Functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
713
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
714 * 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
715 * fwd-para let:: The @code{let*} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
716 * 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
717 * fwd-para between paragraphs:: Movement between paragraphs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
718 * fwd-para within paragraph:: Movement within paragraphs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
719 * 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
720 * 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
721 * 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
722
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
723 Counting: Repetition and Regexps
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
724
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
725 * Why Count Words::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
726 * 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
727 * 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
728 * Counting Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
729
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
730 The @code{count-words-region} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
731
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
732 * 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
733 * 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
734
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
735 Counting Words in a @code{defun}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
736
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
737 * Divide and Conquer::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
738 * Words and Symbols:: What to count?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
739 * Syntax:: What constitutes a word or symbol?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
740 * 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
741 * 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
742 * 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
743 * 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
744 * 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
745 * 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
746 * 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
747
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
748 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
749
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
750 * 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
751 * append:: Attach one list to another.
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 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
754
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
755 * Sorting:: Sorting lists.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
756 * Files List:: Making a list of files.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
757 * Counting function definitions::
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 Readying a Graph
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 * Columns of a graph::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
762 * 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
763 * recursive-graph-body-print::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
764 * Printed Axes::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
765 * Line Graph Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
766
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
767 Your @file{.emacs} File
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
768
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
769 * Default Configuration::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
770 * 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
771 * defcustom:: Emacs will write code for you.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
772 * 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
773 * Text and Auto-fill:: Automatically wrap lines.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
774 * Mail Aliases:: Use abbreviations for email addresses.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
775 * 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
776 * Keybindings:: Create some personal keybindings.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
777 * Keymaps:: More about key binding.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
778 * 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
779 * Autoload:: Make functions available.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
780 * 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
781 * 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
782 * Miscellaneous::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
783 * 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
784
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
785 Debugging
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 * 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
788 * 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
789 * 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
790 * 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
791 * Debugging Exercises::
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 Handling the Kill Ring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
794
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
795 * 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
796 * 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
797 * yank-pop:: Insert first element pointed to.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
798
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
799 The @code{rotate-yank-pointer} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
801 * Understanding rotate-yk-ptr::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
802 * 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
803
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
804 The Body of @code{rotate-yank-pointer}
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 * 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
807 * 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
808 * Remainder Function:: The remainder, @code{%}, function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
809 * 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
810 * 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
811
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
812 @code{yank}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
813
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
814 * 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
815 * 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
816
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
817 A Graph with Labelled Axes
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 * Labelled Example::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
820 * 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
821 * 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
822 * print-X-axis:: Print a horizontal label.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
823 * 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
824
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
825 The @code{print-Y-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 * 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
828 * 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
829 * 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
830 * 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
831 * 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
832
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
833 The @code{print-X-axis} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
834
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
835 * 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
836 * 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
837
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
838 Printing the Whole Graph
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 * The final version:: A few changes.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
841 * Test print-graph:: Run a short test.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
842 * 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
843 * lambda:: How to write an anonymous function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
844 * 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
845 * 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
846 * Final printed graph:: The graph itself!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
847
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
848 @end detailmenu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
849 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
850
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
851 @node Preface, List Processing, Top, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
852 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
853 @unnumbered Preface
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
854
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
855 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
856 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
857 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
858 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
859 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
860 extension to the editor.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
861
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
862 (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
863 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
864 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
865 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
866 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
867 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
868 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
869 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
870
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
871 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
872 * Why:: Why learn Emacs Lisp?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
873 * 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
874 * 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
875 * Lisp History::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
876 * 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
877 * Thank You::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
878 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
879
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
880 @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
881 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
882 @unnumberedsec Why Study Emacs Lisp?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
883 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
884
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
885 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
886 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
887 you would any other programming language.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
888
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
889 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
890 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
891 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
892 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
893 can teach yourself to go further.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
894
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
895 @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
896 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
897 @unnumberedsec On Reading this Text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
898
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
899 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
900 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
901 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
902 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
903 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
904 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
905 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
906 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
907 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
908 there.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
909
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
910 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
911 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
912 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
913 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
914 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
915 implemented.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
916 Also, I
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
917 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
918 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
919 having a dragon's cave of treasures.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
920
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
921 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
922 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
923 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
924 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
925 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
926 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
927 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
928 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
929 around your home town.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
930
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
931 @ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
932 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
933 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
934 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
935 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
936 `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
937 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
938 @end ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
939
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
940 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
941 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
942 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
943 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
944 advantage.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
945
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
946 @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
947 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
948 @unnumberedsec For Whom This is Written
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
949
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
950 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
951 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
952 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
953 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
954
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
955 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
956
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
957 @quotation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
958 @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
959 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
960
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
961 @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
962 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
963 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
964 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
965 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
966 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
967 @end quotation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
968
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
969 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
970
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
971 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
972 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
973 different context, or to review it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
974
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
975 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
976 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
977 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
978 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
979 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
980 information is formally introduced.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
981
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
982 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
983 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
984 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
985 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
986 what is important, and concentrate on it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
987
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
988 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
989 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
990 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
991 as a daunting mountain.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
992
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
993 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
994 document,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
995 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
996 @cite{The GNU Emacs Lisp Reference Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
997 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
998 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
999 @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
1000 Emacs Lisp Reference Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1001 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1002 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
1003 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
1004 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
1005 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
1006 @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
1007 when you are writing your own programs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1008
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1009 @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
1010 @unnumberedsec Lisp History
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1011 @cindex Lisp history
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1012
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1013 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
1014 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
1015 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
1016 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
1017
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1018 @cindex Maclisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1019 @cindex Common Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1020 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
1021 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
1022 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
1023 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
1024 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
1025
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1026 @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
1027 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1028 @unnumberedsec A Note for Novices
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1029
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1030 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
1031 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
1032 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
1033 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
1034 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
1035 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
1036
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1037 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
1038 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
1039 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
1040 (@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
1041 @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
1042 @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
1043 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
1044 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
1045 @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
1046 (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
1047 @key{ALT}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1048 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
1049 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
1050 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
1051 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
1052 @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
1053 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
1054 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
1055 press the @key{\} key.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1056
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1057 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
1058 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
1059 @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
1060 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
1061 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
1062 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
1063 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
1064 Numeric Arguments, emacs, The GNU Emacs Manual}.
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 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
1067 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
1068 (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
1069
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1070 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
1071 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
1072 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
1073
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1074 @node Thank You, , Note for Novices, Preface
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1075 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1076 @unnumberedsec Thank You
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1077
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1078 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
1079 @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
1080 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
1081 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
1082 @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
1083 encouragement. My mistakes are my own.
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 @flushright
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1086 Robert J. Chassell
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1087 @end flushright
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1088
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1089 @c ================ Beginning of main text ================
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1090
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1091 @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
1092
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1093 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1094 \par\vfill\supereject
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1095 \headings off
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1096 \ifodd\pageno
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1097 \par\vfill\supereject
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1098 \else
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1099 \par\vfill\supereject
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1100 \page\hbox{}\page
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1101 \par\vfill\supereject
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1102 \fi
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1103 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1104
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1105 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1106 @headings off
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1107 @evenheading @thispage @| @| @thischapter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1108 @oddheading @thissection @| @| @thispage
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1109 @pageno = 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1110 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1111
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1112 @node List Processing, Practicing Evaluation, Preface, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1113 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1114 @chapter List Processing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1115
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1116 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
1117 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
1118 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
1119 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
1120 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
1121 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
1122 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
1123 @samp{'}. Lists are the basis of Lisp.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1124
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1125 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1126 * Lisp Lists:: What are lists?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1127 * 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
1128 * Making Errors:: Generating an error message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1129 * 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
1130 * Lisp Interpreter:: What the Lisp interpreter does.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1131 * Evaluation:: Running a program.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1132 * Variables:: Returning a value from a variable.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1133 * Arguments:: Passing information to a function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1134 * 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
1135 * Summary:: The major points.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1136 * Error Message Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1137 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1138
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1139 @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
1140 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1141 @section Lisp Lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1142 @cindex Lisp Lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1143
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1144 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
1145 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
1146 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
1147 to be familiar with:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1148
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1149 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1150 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1151 '(rose
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1152 violet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1153 daisy
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1154 buttercup)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1155 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1156 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1157
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1158 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1159 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
1160 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
1161 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
1162 @cindex Flowers in a field
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1163
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1164 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1165 * 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
1166 * Lisp Atoms:: Elemental entities.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1167 * 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
1168 * 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
1169 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1170
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1171 @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
1172 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1173 @unnumberedsubsec Numbers, Lists inside of Lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1174 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1175
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1176 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
1177 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
1178 separated by whitespace.
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 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
1181 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
1182 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
1183 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
1184 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
1185 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
1186 @samp{.} as punctuation marks.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1187
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1188 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1189 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
1190
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1191 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1192 '(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
1193 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1194
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1195 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
1196 @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
1197 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
1198 @samp{of}, @samp{it}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1199
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1200 @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
1201 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1202 @subsection Lisp Atoms
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1203 @cindex Lisp Atoms
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1204
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1205 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
1206 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
1207 `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
1208 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
1209 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
1210 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
1211 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
1212 @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
1213
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1214 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
1215 right next to a parenthesis.
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 @samp{empty list} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1218 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
1219 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
1220 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
1221 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
1222 @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
1223 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
1224
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1225 @cindex Symbolic expressions, introduced
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1226 @cindex @samp{expression} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1227 @cindex @samp{form} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1228 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
1229 @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
1230 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
1231 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
1232 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
1233 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
1234 as a synonym for expression.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1235
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1236 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
1237 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
1238 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
1239 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
1240 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
1241 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
1242 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
1243 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
1244 unsplittable.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1245
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1246 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
1247 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
1248 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
1249 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
1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1251 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
1252 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
1253 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
1254 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
1255 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
1256 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
1257 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
1258 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
1259 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
1260 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
1261 parentheses, without any non-Lisp punctuation.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1262
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1263 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1264 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
1265 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
1266 @cindex Text between double quotation marks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1267
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1268 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1269 '(this list includes "text between quotation marks.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1270 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1271
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1272 @cindex @samp{string} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1273 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1274 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
1275 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
1276 @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
1277 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
1278 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
1279 used differently.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1280
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1281 @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
1282 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1283 @subsection Whitespace in Lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1284 @cindex Whitespace in lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1285
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1286 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1287 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
1288 of the Lisp language,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1289
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1290 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1291 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1292 '(this list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1293 looks like this)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1294 @end group
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1298 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1299 is exactly the same as this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1302 '(this list looks like this)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1303 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1304
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1305 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
1306 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
1307 @samp{this} in that order.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1308
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1309 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
1310 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
1311 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
1312 order to tell them apart.)
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 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
1315 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
1316 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
1317 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
1318 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
1319 (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
1320 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
1321
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1322 @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
1323 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1324 @subsection GNU Emacs Helps You Type Lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1325 @cindex Help typing lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1326 @cindex Formatting help
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1327
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1328 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
1329 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
1330 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
1331 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
1332 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
1333 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
1334 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
1335 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
1336 the enclosing list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1337
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1338 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
1339 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
1340 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
1341 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
1342 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
1343 Manual}, for more information about Emacs' modes.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1344
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1345 @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
1346 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1347 @section Run a Program
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1348 @cindex Run a program
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1349 @cindex Program, running one
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 @cindex @samp{evaluate} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1352 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
1353 (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
1354 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
1355 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
1356 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
1357 three things that you really want!)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1358
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1359 @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
1360 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
1361 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
1362 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
1363 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
1364 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
1365 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
1366 @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
1367 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
1368 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
1369
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1370 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1371 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
1372 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
1373 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
1374
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1375 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1376 (+ 2 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1377 @end smallexample
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 @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
1380 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1381 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
1382 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
1383 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
1384 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
1385 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
1386
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1387 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1388 '(this is a quoted list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1389 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1390
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1391 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1392 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
1393
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1394 @cindex Lisp interpreter, explained
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1395 @cindex Interpreter, Lisp, explained
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1396 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
1397 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
1398 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
1399 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
1400 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
1401
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1402 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
1403 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
1404 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
1405 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
1406 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
1407
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1408 @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
1409 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1410 @section Generate an Error Message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1411 @cindex Generate an error message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1412 @cindex Error message generation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1413
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1414 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
1415 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
1416 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
1417 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
1418 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
1419 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
1420 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
1421 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
1422
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1423 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
1424 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
1425
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1426 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
1427 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
1428 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
1429 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
1430 C-e}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1431
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1432 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1433 (this is an unquoted list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1434 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1435
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1436 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1437 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
1438 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
1439 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
1440 earlier, version 20 result.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1441
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1442 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1443 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1444 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
1445 you will see the following in it:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1446
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1447 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1448 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1449 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1450 Debugger entered--Lisp error: (void-function this)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1451 (this is an unquoted list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1452 eval((this is an unquoted list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1453 eval-last-sexp-1(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1454 eval-last-sexp(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1455 call-interactively(eval-last-sexp)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1456 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1457 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1458 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1459
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1460 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1461 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1462 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
1463 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
1464 debugger window go away, type:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1465
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1466 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1467 q
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1468 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1471 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
1472 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
1473 it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1474
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1475 @cindex @samp{function} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1476 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
1477
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1478 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
1479 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
1480 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
1481 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
1482 `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
1483 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
1484
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1485 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
1486 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
1487 @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
1488 backwards.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1489
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1490 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1491 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
1492
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1493 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1494 Debugger entered--Lisp error: (void-function this)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1495 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1496
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1497 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1498 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
1499 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
1500 @samp{void-function this}.
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 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
1503
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1504 @cindex @samp{function} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1505 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
1506 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
1507 @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
1508 computer to do something.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1509
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1510 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
1511 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
1512 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
1513
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1514 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
1515 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
1516 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
1517 contain the instructions is `void'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1518
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1519 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
1520 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
1521 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
1522 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
1523
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1524 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1525 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
1526 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
1527 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1528
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1529 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1530 Symbol's function definition is void:@: this
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1531 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1532
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1533 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1534 (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
1535 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
1536 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
1537
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1538 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
1539 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
1540 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
1541 (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
1542 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
1543 moment.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1544
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1545 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
1546 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
1547 @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
1548
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1549 @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
1550 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1551 @section Symbol Names and Function Definitions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1552 @cindex Symbol names
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1553
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1554 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
1555 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
1556 @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
1557 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
1558 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
1559 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
1560 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
1561 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
1562 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
1563 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
1564
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1565 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
1566 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
1567 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
1568 (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
1569 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
1570
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1571 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
1572 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
1573 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
1574 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
1575 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
1576 (@xref{Install, , Install a Function Definition}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1577
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1578 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
1579 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
1580 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
1581 @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
1582 start with @samp{rmail-}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1583
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1584 @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
1585 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1586 @section The Lisp Interpreter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1587 @cindex Lisp interpreter, what it does
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1588 @cindex Interpreter, what it does
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1589
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1590 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
1591 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
1592 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
1593 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
1594 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
1595 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
1596 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
1597 Otherwise, the interpreter prints an error message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1598
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1599 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
1600 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
1601 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
1602 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
1603 yourself or the computer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1604
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1605 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1606 * Complications:: Variables, Special forms, Lists within.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1607 * Byte Compiling:: Specially processing code for speed.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1608 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1609
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1610 @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
1611 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1612 @unnumberedsubsec Complications
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1613 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1614
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1615 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
1616 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
1617 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
1618 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
1619 in the section on variables. (@xref{Variables}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1620
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1621 @cindex Special form
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1622 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
1623 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
1624 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
1625 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
1626 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
1627
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1628 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
1629 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
1630 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
1631 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
1632 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
1633 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
1634 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
1635 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
1636 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
1637 used by the enclosing expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1638
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1639 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
1640 the next.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1641
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1642 @node Byte Compiling, , Complications, Lisp Interpreter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1643 @subsection Byte Compiling
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1644 @cindex Byte compiling
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1645
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1646 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
1647 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
1648 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
1649 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
1650 runs faster than humanly readable code.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1651
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1652 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
1653 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
1654 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
1655 @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
1656 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
1657 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
1658
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1659 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
1660 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
1661 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
1662 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
1663 compilation.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1664
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1665 @node Evaluation, Variables, Lisp Interpreter, List Processing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1666 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1667 @section Evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1668 @cindex Evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1669
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1670 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
1671 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
1672 `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
1673 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
1674 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
1675 Collegiate Dictionary}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1676
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1677 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
1678 @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
1679 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
1680 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
1681 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
1682 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
1683 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
1684 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
1685
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1686 @cindex @samp{side effect} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1687 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
1688 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
1689 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
1690 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
1691 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
1692 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
1693
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1694 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
1695 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
1696 or else produce an error.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1697
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1698 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1699 * Evaluating Inner Lists:: Lists within lists...
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1700 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1701
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1702 @node Evaluating Inner Lists, , Evaluation, Evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1703 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1704 @subsection Evaluating Inner Lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1705 @cindex Inner list evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1706 @cindex Evaluating inner lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1707
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1708 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
1709 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
1710 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
1711 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
1712 expressions.
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1715 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
1716 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
1717
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1718 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1719 (+ 2 (+ 3 3))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1720 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1721
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1722 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1723 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
1724
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1725 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
1726 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
1727 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
1728 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
1729 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
1730
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1731 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
1732 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
1733 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
1734 @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
1735 `evaluate last symbolic expression'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1736
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1737 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
1738 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
1739 expression, or inside the expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1740
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1741 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1742 Here is another copy of the expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1743
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1744 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1745 (+ 2 (+ 3 3))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1746 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1747
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1748 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1749 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
1750 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
1751 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
1752 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
1753 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
1754 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
1755 evaluates the expression @code{(+ 3 3)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1756
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1757 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
1758 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
1759 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
1760 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
1761 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
1762 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
1763 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
1764 see in the next section.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1765
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1766 @node Variables, Arguments, Evaluation, List Processing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1767 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1768 @section Variables
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1769 @cindex Variables
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1770
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1771 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
1772 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
1773 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
1774 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
1775 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
1776 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
1777 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
1778 @dfn{variable}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1779
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1780 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
1781 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
1782 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
1783 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
1784 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
1785 ``great programming center''.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1786
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1787 @ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1788 (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
1789 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
1790 string; these are discussed later.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1791 @end ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1792
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1793 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
1794 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
1795 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
1796 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
1797 function definition, and vice-versa.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1798
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1799 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1800 * fill-column Example::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1801 * 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
1802 without a function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1803 * 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
1804 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1805
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1806 @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
1807 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1808 @unnumberedsubsec @code{fill-column}, an Example Variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1809 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1810
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1811 @findex fill-column, @r{an example variable}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1812 @cindex Example variable, @code{fill-column}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1813 @cindex Variable, example of, @code{fill-column}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1814 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
1815 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
1816 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
1817 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
1818 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
1819 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
1820
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1821 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1822 fill-column
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1823 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1824
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1825 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1826 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
1827 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
1828 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
1829 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
1830 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
1831 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
1832 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
1833 the value is known.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1834
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1835 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
1836 @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
1837 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
1838 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
1839
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1840 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
1841 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
1842 this.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1843
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1844 @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
1845 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1846 @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
1847 @cindex Symbol without function error
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1848 @cindex Error for symbol without function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1849
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1850 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
1851 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
1852 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
1853
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1854 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
1855 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
1856 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
1857 Try evaluating this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1858
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1859 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1860 (fill-column)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1861 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1862
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1863 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1864 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1865 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
1866 that says:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1867
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1868 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1869 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1870 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1871 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
1872 (fill-column)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1873 eval((fill-column))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1874 eval-last-sexp-1(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1875 eval-last-sexp(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1876 call-interactively(eval-last-sexp)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1877 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1878 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1879 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1880
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1881 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1882 (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
1883 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
1884
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1885 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1886 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
1887
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1888 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1889 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
1890 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1891
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1892 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1893 (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
1894 another key.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1895
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1896 @node Void Variable, , Void Function, Variables
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1897 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1898 @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
1899 @cindex Symbol without value error
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1900 @cindex Error for symbol without value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1901
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1902 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
1903 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
1904 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
1905 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
1906 type @kbd{C-x C-e}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1907
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1908 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1909 (+ 2 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1910 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1911
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1912 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1913 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1914 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
1915 says:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1916
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1917 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1918 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1919 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1920 Debugger entered--Lisp error: (void-variable +)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1921 eval(+)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1922 eval-last-sexp-1(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1923 eval-last-sexp(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1924 call-interactively(eval-last-sexp)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1925 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1926 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1927 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1928
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1929 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1930 (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
1931 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
1932
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1933 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
1934 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
1935 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
1936 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
1937 have a definition.
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 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
1940 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
1941 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
1942 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
1943 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
1944 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
1945 @code{+} by itself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1946
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1947 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
1948 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
1949 variable was void.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1950
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1951 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1952 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
1953
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1954 @example
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1955 Symbol's value as variable is void:@: +
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1956 @end example
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1957
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1958 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1959 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
1960
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1961 @node Arguments, set & setq, Variables, List Processing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1962 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1963 @section Arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1964 @cindex Arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1965 @cindex Passing information to functions
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 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
1968 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
1969 as follows:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1972 (+ 2 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1973 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1974
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1975 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
1976 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
1977 the @code{+}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1978
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1979 @cindex @samp{argument} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1980 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
1981 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
1982 or @dfn{passed} to the function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1983
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
1984 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
1985 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
1986 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
1987 @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
1988 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
1989 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
1990 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
1991 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
1992 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
1993 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
1994 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
1995 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
1996 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
1997 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
1998 `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
1999 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
2000 (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
2001 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
2002 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
2003
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2004 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2005 * 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
2006 * 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
2007 of a variable or list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2008 * 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
2009 variable number of arguments.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2010 * 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
2011 to a function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2012 * message:: A useful function for sending messages.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2013 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2014
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2015 @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
2016 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2017 @subsection Arguments' Data Types
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2018 @cindex Data types
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2019 @cindex Types of data
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2020 @cindex Arguments' data types
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2021
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2022 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
2023 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
2024 @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
2025 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
2026
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2027 @findex concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2028 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
2029 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
2030 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
2031 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
2032 following:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2033
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2034 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2035 (concat "abc" "def")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2036 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2037
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2038 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2039 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
2040
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2041 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
2042 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
2043 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
2044 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
2045 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
2046 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
2047 punctuations) from the beginning of the string.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2048
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2049 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2050 For example, if you evaluate the following:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2053 (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
2054 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2055
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2056 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2057 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
2058 string and the two numbers.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2059
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2060 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
2061 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
2062 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
2063 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
2064 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
2065 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
2066 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
2067 atom such as a number or symbol.
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 @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
2070 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2071 @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
2072
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2073 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
2074 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
2075 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
2076
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2077 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2078 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
2079 C-e}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2080
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2081 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2082 (+ 2 fill-column)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2083 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2084
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2085 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2086 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
2087 @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
2088 @code{fill-column} is 72.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2089
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2090 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
2091 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
2092 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
2093 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
2094 @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
2095 @code{(number-to-string (+ 2 fill-column))}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2096
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2097 @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
2098 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2099 (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
2100 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2101
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2102 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2103 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
2104 @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
2105 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
2106 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
2107 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
2108 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
2109 @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
2110
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2111 @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
2112 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2113 @subsection Variable Number of Arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2114 @cindex Variable number of arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2115 @cindex Arguments, variable number of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2116
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2117 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
2118 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
2119 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
2120 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
2121 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
2122
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2123 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2124 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
2125
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2126 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2127 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2128 (+) @result{} 0
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2129
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2130 (*) @result{} 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2131 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2132 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2133
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2134 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2135 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
2136
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2137 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2138 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2139 (+ 3) @result{} 3
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2140
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2141 (* 3) @result{} 3
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2142 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2143 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2144
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2145 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2146 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
2147
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2148 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2149 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2150 (+ 3 4 5) @result{} 12
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2151
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2152 (* 3 4 5) @result{} 60
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2153 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2154 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2155
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2156 @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
2157 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2158 @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
2159 @cindex Wrong type of argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2160 @cindex Argument, wrong type of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2161
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2162 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
2163 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
2164 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
2165 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
2166 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
2167 @kbd{C-x C-e}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2168
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2169 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2170 (+ 2 'hello)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2171 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2172
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2173 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2174 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
2175 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
2176 @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
2177 @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
2178 could not carry out its addition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2179
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2180 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2181 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
2182 @file{*Backtrace*} buffer that says:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2183
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2184 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2185 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2186 @group
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 Debugger entered--Lisp error:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2189 (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
2190 +(2 hello)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2191 eval((+ 2 (quote hello)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2192 eval-last-sexp-1(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2193 eval-last-sexp(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2194 call-interactively(eval-last-sexp)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2195 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2196 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2197 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2198
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2199 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2200 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
2201 learn how to read it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2202
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2203 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
2204 @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
2205 @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
2206 kind of argument the @code{+} expected.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2207
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2208 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
2209 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
2210 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
2211 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
2212 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
2213 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
2214 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
2215 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
2216 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
2217 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
2218 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
2219 numeric value of marker positions as numbers.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2220
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2221 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
2222 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
2223 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
2224 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
2225 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
2226 @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
2227 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
2228 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
2229 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
2230 @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
2231
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2232 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
2233 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
2234 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
2235 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
2236 @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
2237
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2238 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2239 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
2240 message that says:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2241
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2242 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2243 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
2244 @end smallexample
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 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
2247 @file{*Backtrace*} buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2248
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2249 @node message, , Wrong Type of Argument, Arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2250 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2251 @subsection The @code{message} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2252 @findex message
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 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
2255 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
2256 that we will describe it here.
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2259 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
2260 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
2261
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2262 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2263 (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
2264 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2265
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2266 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
2267 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
2268 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
2269 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
2270 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
2271 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
2272 @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
2273 detail}, for an example of this.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2274
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2275 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
2276 @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
2277 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
2278 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
2279 @samp{%s} is.
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2282 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
2283 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
2284
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2285 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2286 (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
2287 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2288
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2289 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2290 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
2291 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
2292 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
2293 of @code{%s}.
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 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
2296 @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
2297 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
2298
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2299 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2300 (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
2301 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2302
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2303 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2304 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
2305 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
2306 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
2307 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
2308 anything that is not a number.}.
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 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
2311 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
2312 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
2313 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
2314
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2315 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2316 For example, if you evaluate the following,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2317
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2318 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2319 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2320 (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
2321 (- fill-column 14) "pink elephants")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2322 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2323 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2324
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2325 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2326 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
2327 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
2328
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2329 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
2330 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
2331 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
2332 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
2333 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
2334
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2335 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
2336 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
2337 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
2338 for @samp{%s}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2339
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2340 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2341 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2342 (message "He saw %d %s"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2343 (- fill-column 34)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2344 (concat "red "
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2345 (substring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2346 "The quick brown foxes jumped." 16 21)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2347 " leaping."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2348 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2349 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2350
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2351 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
2352 @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
2353 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
2354 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
2355 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
2356 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
2357
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2358 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
2359 foxes leaping."} appears in my echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2360
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2361 @node set & setq, Summary, Arguments, List Processing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2362 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2363 @section Setting the Value of a Variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2364 @cindex Variable, setting value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2365 @cindex Setting value of variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2366
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2367 @cindex @samp{bind} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2368 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
2369 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
2370 @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
2371 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
2372
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2373 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
2374 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
2375
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2376 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2377 * Using set:: Setting values.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2378 * Using setq:: Setting a quoted value.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2379 * Counting:: Using @code{setq} to count.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2380 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2381
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2382 @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
2383 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2384 @subsection Using @code{set}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2385 @findex set
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 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
2388 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
2389 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
2390
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2391 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2392 (set 'flowers '(rose violet daisy buttercup))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2393 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2394
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2395 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2396 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
2397 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
2398 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
2399 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
2400 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
2401 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
2402 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
2403 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
2404 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
2405
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2406 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
2407 @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
2408 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
2409
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2410 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2411 flowers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2412 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2415 When you evaluate @code{flowers}, the list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2416 @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
2417
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2418 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
2419 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
2420 @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
2421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2422 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2423 'flowers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2424 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2425
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2426 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
2427 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
2428 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
2429 @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
2430 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
2431 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
2432 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
2433 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
2434 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
2435 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
2436 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
2437 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
2438
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2439 @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
2440 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2441 @subsection Using @code{setq}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2442 @findex setq
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 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
2445 @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
2446 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
2447 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
2448 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
2449 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
2450 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
2451
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2452 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
2453 @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
2454 is used:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2455
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2456 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2457 (setq carnivores '(lion tiger leopard))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2458 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2461 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
2462 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
2463 means @code{quote}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2464
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2465 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2466 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
2467
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2468 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2469 (set 'carnivores '(lion tiger leopard))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2470 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2471
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2472 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
2473 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
2474 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
2475 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
2476 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
2477 to the symbol @code{herbivores}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2478
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2479 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2480 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2481 (setq trees '(pine fir oak maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2482 herbivores '(gazelle antelope zebra))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2483 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2484 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2485
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2486 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2487 (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
2488 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
2489 formatted lists.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2490
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2491 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
2492 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
2493 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
2494 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
2495 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
2496 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
2497 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
2498 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
2499
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2500 @node Counting, , Using setq, set & setq
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2501 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2502 @subsection Counting
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2503 @cindex Counting
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2504
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2505 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
2506 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
2507 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
2508 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
2509 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
2510 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
2511 @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
2512 evaluated.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2513
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2514 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2515 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2516 (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
2517
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2518 (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
2519
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2520 counter ; @r{This is the counter.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2521 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2522 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2523
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2524 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2525 (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
2526 defun, , Change a Function Definition}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2527
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2528 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
2529 @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
2530 @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
2531 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
2532 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
2533 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
2534 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
2535 the counter will be incremented.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2536
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2537 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
2538 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
2539 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
2540 @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
2541 @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
2542 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
2543 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
2544 @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
2545 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
2546
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2547 @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
2548 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2549 @section Summary
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 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
2552 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
2553 becomes easier as you progress onwards.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2554
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2555 In summary,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2556
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2557 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2558
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2559 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2560 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
2561
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2562 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2563 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
2564 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
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 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
2568 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
2569 quotation marks, or numbers.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2570
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2571 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2572 A number evaluates to itself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2573
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2574 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2575 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
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 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
2579
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2580 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2581 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
2582 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
2583 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
2584
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2585 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2586 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
2587 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
2588 would if the quote were not there.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2589
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2590 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2591 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
2592 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
2593 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
2594
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2595 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2596 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
2597 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
2598 ``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
2599 create a side effect.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2600 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2601
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2602 @node Error Message Exercises, , Summary, List Processing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2603 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2604 @section Exercises
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2605
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2606 A few simple exercises:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2607
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2608 @itemize @bullet
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 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
2611 not within parentheses.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2612
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2613 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2614 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
2615 between parentheses.
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 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2618 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
2619
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2620 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2621 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
2622 evaluated.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2623 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2624
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2625 @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
2626 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2627 @chapter Practicing Evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2628 @cindex Practicing evaluation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2629 @cindex Evaluation practice
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2630
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2631 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
2632 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
2633 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
2634 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
2635 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
2636 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
2637 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
2638 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
2639
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2640 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2641 * 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
2642 causes evaluation.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2643 * Buffer Names:: Buffers and files are different.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2644 * 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
2645 * 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
2646 * 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
2647 the buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2648 * Evaluation Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2649 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2650
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2651 @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
2652 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2653 @unnumberedsec How to Evaluate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2654 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2655
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2656 @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
2657 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
2658 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
2659 how Emacs works.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2660
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2661 @cindex @samp{interactive function} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2662 @cindex @samp{command} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2663 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
2664 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
2665 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
2666 @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
2667 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
2668 @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
2669 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
2670 definitions. @xref{Interactive, , Making a Function Interactive}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2671
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2672 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
2673 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
2674 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
2675 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
2676 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
2677
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2678 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
2679 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
2680 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
2681 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
2682
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2683 @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
2684 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2685 @section Buffer Names
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2686 @findex buffer-name
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2687 @findex buffer-file-name
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2688
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2689 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
2690 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
2691 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
2692 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
2693 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
2694 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
2695 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
2696 @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
2697
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2698 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
2699 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
2700 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
2701 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
2702 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
2703 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
2704 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
2705 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
2706 and is thus saved permanently.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2707
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2708 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2709 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
2710 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
2711 typing @kbd{C-x C-e}.
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2714 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2715 (buffer-name)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2716
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2717 (buffer-file-name)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2718 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2719 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2720
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2721 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2722 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
2723 evaluating @code{(buffer-name)}, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2724 @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
2725 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
2726 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
2727 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
2728 @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
2729 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
2730 @xref{Variables}.)
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 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
2733 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
2734 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
2735 ``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
2736 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
2737 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
2738 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
2739
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2740 @cindex Buffer, history of word
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2741 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
2742 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
2743 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
2744 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
2745 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
2746 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
2747 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
2748 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
2749 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
2750 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
2751 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
2752 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
2753 and cultural center in its own right.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2754
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2755 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
2756 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
2757 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
2758 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
2759 @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
2760
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2761 @cindex @code{nil}, history of word
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2762 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
2763 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
2764 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
2765 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
2766 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
2767 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
2768 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
2769 @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
2770 @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
2771 list, @code{()}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2772
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2773 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
2774 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
2775 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
2776 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
2777 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
2778
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2779 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2780 (buffer-name)"*scratch*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2781 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2782
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2783 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2784 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
2785 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
2786 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
2787 this book), this feature is very useful.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2788
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2789 @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
2790 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2791 @section Getting Buffers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2792 @findex current-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2793 @findex other-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2794 @cindex Getting a buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2795
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2796 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
2797 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
2798 @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
2799 you get is the buffer itself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2801 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
2802 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
2803 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
2804 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
2805 @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
2806 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
2807 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
2808 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
2809 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
2810 @code{current-buffer}.
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 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
2813 @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
2814 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
2815 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
2816 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
2817 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
2818 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
2819
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2820 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2821 Here is an expression containing the function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2822
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2823 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2824 (current-buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2825 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2826
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2827 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2828 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
2829 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
2830 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
2831
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2832 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
2833 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
2834 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
2835
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2836 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
2837 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
2838 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
2839 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
2840
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2841 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2842 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
2843
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2844 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2845 (other-buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2846 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2849 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
2850 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
2851 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
2852 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
2853 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
2854 subtlety that I often forget.}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2855
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2856 @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
2857 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2858 @section Switching Buffers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2859 @findex switch-to-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2860 @findex set-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2861 @cindex Switching to a buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2862
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2863 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
2864 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
2865 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
2866 different buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2867
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2868 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
2869 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
2870 @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
2871 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
2872 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
2873 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
2874 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
2875 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
2876 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
2877 interpreter to evaluate the interactive function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2878 @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
2879 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
2880 @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
2881 @code{forward-sentence}, and so on.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2882
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2883 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
2884 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
2885 does.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2886
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2887 @need 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2888 Here is the Lisp expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2889
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2890 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2891 (switch-to-buffer (other-buffer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2892 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2893
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2894 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2895 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
2896 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
2897 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
2898 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
2899 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
2900 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
2901 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
2902 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
2903 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
2904 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
2905 (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
2906 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
2907 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
2908 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
2909 following more complex expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2910
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2911 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2912 (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
2913 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2914
42562
fb149efd0c72 Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents: 42506
diff changeset
2915 @c noindent
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2916 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
2917 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
2918 @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
2919 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
2920 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
2921 to go to another visible buffer.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2922
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2923 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
2924 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
2925 @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
2926 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
2927 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
2928 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
2929 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
2930 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
2931
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2932 @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
2933 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
2934 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
2935 @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
2936 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
2937 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
2938 there until the command finishes running).
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 @cindex @samp{call} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2941 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
2942 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
2943 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
2944 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
2945 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
2946 or her.
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 @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
2949 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2950 @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
2951 @cindex Size of buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2952 @cindex Buffer size
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2953 @cindex Point location
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2954 @cindex Location of point
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2955
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2956 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
2957 @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
2958 @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
2959 the location of point within it.
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 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
2962 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
2963 characters in the buffer.
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2966 (buffer-size)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2967 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2968
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2969 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2970 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
2971 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
2972
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2973 @cindex @samp{point} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2974 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
2975 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
2976 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
2977 beginning of the buffer up to point.
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2980 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
2981 the following expression in the usual way:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2982
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2983 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2984 (point)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2985 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2986
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2987 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2988 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
2989 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
2990 book.
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2993 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
2994 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
2995
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2996 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2997 (point)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2998 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
2999
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3000 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3001 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
3002 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
3003
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3004 @cindex @samp{narrowing} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3005 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
3006 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
3007 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
3008 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
3009 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
3010 @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
3011 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
3012 value of point in the current buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3013
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3014 @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
3015 @section Exercise
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3016
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3017 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
3018 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
3019
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3020 @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
3021 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3022 @chapter How To Write Function Definitions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3023 @cindex Definition writing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3024 @cindex Function definition writing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3025 @cindex Writing a function definition
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 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
3028 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
3029 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
3030 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
3031 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
3032 (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
3033 symbol refers to it.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3034
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3035 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3036 * Primitive Functions::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3037 * defun:: The @code{defun} special form.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3038 * Install:: Install a function definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3039 * Interactive:: Making a function interactive.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3040 * Interactive Options:: Different options for @code{interactive}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3041 * Permanent Installation:: Installing code permanently.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3042 * let:: Creating and initializing local variables.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3043 * if:: What if?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3044 * else:: If--then--else expressions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3045 * 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
3046 * 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
3047 * Review::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3048 * defun Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3049 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3050
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3051 @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
3052 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3053 @unnumberedsec An Aside about Primitive Functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3054 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3055 @cindex Primitive functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3056 @cindex Functions, primitive
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3057
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3058 @cindex C language primitives
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3059 @cindex Primitives written in C
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3060 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
3061 @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
3062 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
3063 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
3064 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
3065 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
3066 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
3067 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
3068 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
3069
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3070 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
3071 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
3072 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
3073 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
3074 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
3075 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
3076
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3077 @node defun, Install, Primitive Functions, Writing Defuns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3078 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3079 @section The @code{defun} Special Form
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3080 @findex defun
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3081 @cindex Special form of @code{defun}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3082
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3083 @cindex @samp{function definition} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3084 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
3085 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
3086 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
3087 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
3088 (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
3089 @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
3090 called a @dfn{special form}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3091
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3092 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
3093 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
3094 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
3095 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
3096 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
3097 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
3098 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
3099 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
3100
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3101 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
3102 @code{defun}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3103
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3104 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3105 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3106 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
3107 attached.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3108
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3109 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3110 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
3111 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
3112 @code{()}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3113
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3114 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3115 Documentation describing the function. (Technically optional, but
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3116 strongly recommended.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3117
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3118 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3119 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
3120 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
3121 typing an appropriate key or keychord.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3122
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3123 @cindex @samp{body} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3124 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3125 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
3126 function definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3127 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3128
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3129 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
3130 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
3131
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3132 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3133 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3134 (defun @var{function-name} (@var{arguments}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3135 "@var{optional-documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3136 (interactive @var{argument-passing-info}) ; @r{optional}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3137 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3138 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3139 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3140
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3141 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
3142 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
3143 , Making a Function Interactive}, for that information.)
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3146 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3147 (defun multiply-by-seven (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3148 "Multiply NUMBER by seven."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3149 (* 7 number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3150 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3151 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3152
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3153 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
3154 followed by the name of the 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 @cindex @samp{argument list} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3157 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
3158 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
3159 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
3160 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
3161 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
3162 function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3163
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3164 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
3165 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
3166 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
3167 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
3168 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
3169 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
3170 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
3171 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
3172 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
3173 the function clear.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3174
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3175 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
3176 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
3177 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
3178 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
3179 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
3180 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
3181 `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
3182 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
3183 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
3184 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
3185 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
3186 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
3187
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3188 @ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3189 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
3190 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
3191 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
3192 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
3193 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
3194 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
3195 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
3196 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
3197 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
3198 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
3199 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
3200 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
3201 @end ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3202
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3203 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
3204 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
3205 @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
3206 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
3207 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
3208 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
3209 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
3210 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
3211 (@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
3212 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
3213 write.
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 @findex * @r{(multiplication)}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3216 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
3217 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
3218 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
3219 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
3220 @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
3221 function for addition.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3222
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3223 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
3224 @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
3225 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
3226 to evaluate this yet!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3227
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3228 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3229 (multiply-by-seven 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3230 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3231
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3232 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3233 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
3234 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
3235 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
3236 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
3237 @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
3238 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
3239 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
3240 definition begins.
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 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
3243 (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
3244 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
3245 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
3246 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
3247 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
3248 section.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3249
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3250 @node Install, Interactive, defun, Writing Defuns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3251 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3252 @section Install a Function Definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3253 @cindex Install a Function Definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3254 @cindex Definition installation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3255 @cindex Function definition installation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3256
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3257 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
3258 @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
3259 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
3260 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
3261 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
3262 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
3263 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
3264 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
3265 action installs the function definition.
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3268 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3269 (defun multiply-by-seven (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3270 "Multiply NUMBER by seven."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3271 (* 7 number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3272 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3273 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3276 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
3277 @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
3278 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
3279 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
3280 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
3281 @ref{Permanent Installation, , Installing Code Permanently}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3282
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3283
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3284 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3285 * Effect of installation::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3286 * 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
3287 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3288
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3289 @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
3290 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3291 @unnumberedsubsec The effect of installation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3292 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3293
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3294
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3295 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
3296 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
3297 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
3298 echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3299
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3300 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3301 (multiply-by-seven 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3302 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3303
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3304 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
3305 @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
3306 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
3307 @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
3308
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3309 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3310 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3311 multiply-by-seven:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3312 Multiply NUMBER by seven.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3313 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3314 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3315
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3316 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3317 (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
3318
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3319 @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
3320 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3321 @subsection Change a Function Definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3322 @cindex Changing a function definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3323 @cindex Function definition, how to change
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3324 @cindex Definition, how to change
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3325
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3326 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
3327 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
3328 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
3329 very simple.
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 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
3332 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
3333 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
3334 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
3335 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
3336 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
3337 version''.
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3340 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3341 (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
3342 "Multiply NUMBER by seven."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3343 (+ number number number number number number number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3344 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3345 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3346
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3347 @cindex Comments in Lisp code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3348 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
3349 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
3350 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
3351 each line with a semicolon.
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 @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
3354 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
3355 Reference Manual}, for more about comments.
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 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
3358 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
3359 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
3360
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3361 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
3362 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
3363 install it again.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3364
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3365 @node Interactive, Interactive Options, Install, Writing Defuns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3366 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3367 @section Make a Function Interactive
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3368 @cindex Interactive functions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3369 @findex interactive
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3370
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3371 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
3372 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
3373 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
3374 @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
3375 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
3376 @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
3377
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3378 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
3379 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
3380 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
3381 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
3382 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
3383 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
3384
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3385 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3386 * Interactive multiply-by-seven:: An overview.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3387 * 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
3388 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3389
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3390 @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
3391 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3392 @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
3393 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3394
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3395 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
3396 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
3397 interactive version of @code{multiply-by-seven}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3398
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3399 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3400 Here is the code:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3401
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3402 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3403 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3404 (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
3405 "Multiply NUMBER by seven."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3406 (interactive "p")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3407 (message "The result is %d" (* 7 number)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3408 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3409 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3412 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
3413 @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
3414 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
3415 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
3416 @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
3417 echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3418
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3419 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
3420 ways:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3422 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3423 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3424 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
3425 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
3426 @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
3427
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3428 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3429 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
3430 @kbd{C-u 3 M-e}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3431 @end enumerate
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3434 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
3435 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
3436 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
3437
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3438 (@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
3439 to a key.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3440
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3441 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
3442 @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
3443 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
3444 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
3445
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3446 @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
3447 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3448 @subsection An Interactive @code{multiply-by-seven}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3449
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3450 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
3451 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
3452 @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
3453 looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3454
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3455 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3456 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3457 (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
3458 "Multiply NUMBER by seven."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3459 (interactive "p")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3460 (message "The result is %d" (* 7 number)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3461 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3462 @end smallexample
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 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
3465 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
3466 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
3467
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3468 @need 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3469 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
3470 @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
3471
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3472 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3473 (message "The result is %d" (* 7 number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3474 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3475
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3476 @need 1250
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 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
3479 evaluate the line as if it were:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3480
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3481 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3482 (message "The result is %d" (* 7 5))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3483 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3484
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3485 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3486 (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
3487 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
3488 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
3489 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
3490 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
3491
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3492 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
3493 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
3494 @code{message} function}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3495 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
3496 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
3497 @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
3498 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
3499 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
3500 located.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3501
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3502 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
3503 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
3504 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
3505 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
3506 is 35}.
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 (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
3509 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
3510 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
3511 @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
3512 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
3513 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
3514 quotes.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3515
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3516 @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
3517 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3518 @section Different Options for @code{interactive}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3519 @cindex Options for @code{interactive}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3520 @cindex Interactive options
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3521
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3522 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
3523 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
3524 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
3525 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
3526 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
3527 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
3528 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
3529 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
3530 @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
3531
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3532 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3533 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
3534 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
3535 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
3536
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3537 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3538 (interactive "r")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3539 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3540
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3541 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
3542 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
3543 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
3544 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
3545 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
3546 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
3547
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3548 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
3549 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
3550 @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
3551 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
3552 @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
3553 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
3554 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
3555 @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
3556 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
3557 in all.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3558
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3559 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
3560 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
3561 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
3562 beginning and ending of the region:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3563
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3564 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3565 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3566 (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
3567 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3568 (interactive "BAppend to buffer:@: \nr")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3569 @var{body-of-function}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3570 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3571 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3572
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3573 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3574 (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
3575 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
3576 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
3577 @code{append-to-buffer}}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3578
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3579 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
3580 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
3581 @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
3582 this.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3583
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3584 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
3585 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
3586 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
3587 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
3588 technique.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3589
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3590 @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
3591 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3592 @section Install Code Permanently
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3593 @cindex Install code permanently
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3594 @cindex Permanent code installation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3595 @cindex Code installation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3596
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3597 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
3598 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
3599 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
3600 function definition again.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3601
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3602 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
3603 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
3604 doing this:
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 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3607 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3608 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
3609 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
3610 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
3611 the function definitions within it are installed.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3612 @xref{Emacs Initialization, , Your @file{.emacs} File}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3613
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3614 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3615 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
3616 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
3617 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
3618 functions in the files.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3619 @xref{Loading Files, , Loading Files}.
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 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3622 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
3623 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
3624 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
3625 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
3626 Emacs distribution.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3627 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3628
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3629 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
3630 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
3631 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
3632 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
3633 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
3634 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
3635 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
3636 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
3637 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
3638
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3639 @node let, if, Permanent Installation, Writing Defuns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3640 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3641 @section @code{let}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3642 @findex let
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3643
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3644 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
3645 to use in most function definitions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3646
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3647 @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
3648 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
3649 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
3650
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3651 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
3652 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
3653 `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
3654 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
3655 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
3656 different house.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3657
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3658 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
3659 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
3660 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
3661 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
3662 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
3663 @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
3664
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3665 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3666 * Prevent confusion::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3667 * Parts of let Expression::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3668 * Sample let Expression::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3669 * Uninitialized let Variables::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3670 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3671
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3672 @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
3673 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3674 @unnumberedsubsec @code{let} Prevents Confusion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3675 @end ifnottex
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 @cindex @samp{local variable} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3678 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
3679 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
3680 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
3681 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
3682 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
3683 @xref{defun, , The @code{defun} Special Form}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3684
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3685 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
3686 @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
3687 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
3688 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
3689
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3690 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
3691 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
3692 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
3693 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
3694 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
3695 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
3696 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
3697
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3698 @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
3699 @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
3700 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
3701 `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
3702 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
3703 @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
3704 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
3705 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
3706 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
3707 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
3708 `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
3709
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3710 @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
3711 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3712 @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
3713 @cindex @code{let} expression, parts of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3714 @cindex Parts of @code{let} expression
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 @cindex @samp{varlist} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3717 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
3718 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
3719 @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
3720 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
3721 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
3722 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
3723
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3724 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3725 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
3726
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3727 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3728 (let @var{varlist} @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3729 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3730
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3731 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3732 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
3733 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
3734 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
3735 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
3736 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
3737
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3738 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
3739 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
3740 @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
3741 @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
3742
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3743 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
3744 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
3745 template.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3746
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3747 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
3748 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
3749
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3750 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3751 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3752 (let ((@var{variable} @var{value})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3753 (@var{variable} @var{value})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3754 @dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3755 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3756 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3757 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3758
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3759 @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
3760 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3761 @subsection Sample @code{let} Expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3762 @cindex Sample @code{let} expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3763 @cindex @code{let} expression sample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3764
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3765 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
3766 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
3767 @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
3768
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3769 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3770 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3771 (let ((zebra 'stripes)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3772 (tiger 'fierce))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3773 (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
3774 zebra tiger))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3775 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3776 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3777
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3778 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
3779
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3780 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
3781 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
3782 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
3783 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
3784 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
3785 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
3786 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
3787 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
3788 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
3789 the echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3790
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3791 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3792 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
3793 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
3794 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
3795
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3796 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3797 "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
3798 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3799
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3800 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
3801 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
3802 @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
3803 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
3804 second @samp{%s}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3805
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3806 @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
3807 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3808 @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
3809 @cindex Uninitialized @code{let} variables
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3810 @cindex @code{let} variables uninitialized
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3811
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3812 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
3813 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
3814 @code{nil}, as in the following expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3815
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3816 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3817 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3818 (let ((birch 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3819 pine
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3820 fir
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3821 (oak 'some))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3822 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3823 "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
3824 birch pine fir oak))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3825 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3826 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3827
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3828 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3829 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
3830
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3831 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3832 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
3833 appear in your echo area:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3834
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3835 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3836 "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
3837 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3838
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3839 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3840 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
3841 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
3842 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
3843
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3844 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
3845 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
3846 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
3847 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
3848 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
3849 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
3850 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
3851 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
3852 @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
3853 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
3854
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3855 @node if, else, let, Writing Defuns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3856 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3857 @section The @code{if} Special Form
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3858 @findex if
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3859 @cindex Conditional with @code{if}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3860
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3861 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
3862 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
3863 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
3864 @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
3865 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
3866 function @code{beginning-of-buffer}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3867
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3868 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
3869 @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
3870 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
3871 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
3872
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3873 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3874 * if in more detail::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3875 * 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
3876 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3877
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3878 @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
3879 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3880 @unnumberedsubsec @code{if} in more detail
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3881 @end ifnottex
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 @cindex @samp{if-part} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3884 @cindex @samp{then-part} defined
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3885 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
3886 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
3887 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
3888 @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
3889 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
3890
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3891 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
3892 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
3893 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
3894 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
3895 expression easier to read.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3896
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3897 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3898 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3899 (if @var{true-or-false-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3900 @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
3901 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3902 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3905 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
3906 is evaluated by the Lisp interpreter.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3907
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3908 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
3909 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
3910 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
3911
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3912 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3913 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3914 (if (> 5 4) ; @r{if-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3915 (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
3916 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3917 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3918
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3919 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3920 (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
3921 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
3922 @findex > (greater than)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3923
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3924 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
3925 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
3926 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
3927 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
3928 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
3929
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3930 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
3931 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
3932 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
3933 @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
3934 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
3935
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3936 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3937 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3938 (defun type-of-animal (characteristic)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3939 "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
3940 If the CHARACTERISTIC is the symbol `fierce',
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3941 then warn of a tiger."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3942 (if (equal characteristic 'fierce)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3943 (message "It's a tiger!")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3944 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3945 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3946
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3947 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3948 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3949 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
3950 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
3951 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
3952
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3953 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3954 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3955 (type-of-animal 'fierce)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3956
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3957 (type-of-animal 'zebra)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3958
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3959 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3960 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3961
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3962 @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
3963 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3964 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
3965 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
3966 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
3967 printed in the echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3968
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3969 @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
3970 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3971 @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
3972
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3973 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
3974
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3975 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
3976 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
3977 a second for an @code{if} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3978
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3979 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3980 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
3981
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3982 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3983 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3984 (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
3985 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3986 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3987 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3988 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3989
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3990 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3991 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
3992
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3993 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3994 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3995 (defun type-of-animal (characteristic)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3996 "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
3997 If the CHARACTERISTIC is the symbol `fierce',
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3998 then warn of a tiger."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
3999 @var{body: the} @code{if} @var{expression})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4000 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4001 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4002
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4003 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
4004 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
4005 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
4006 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
4007 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
4008 consists of the @code{if} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4009
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4010 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4011 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
4012
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4013 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4014 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4015 (if @var{true-or-false-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4016 @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
4017 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4018 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4019
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4020 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4021 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
4022 looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4023
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4024 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4025 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4026 (if (equal characteristic 'fierce)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4027 (message "It's a tiger!")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4028 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4029 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4030
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4031 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4032 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
4033
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4034 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4035 (equal characteristic 'fierce)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4036 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4037
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4038 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4039 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
4040 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
4041 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
4042 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
4043 this function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4044
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4045 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
4046 @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
4047 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
4048 '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
4049 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
4050 @code{(message "It's tiger!")}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4051
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4052 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
4053 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
4054 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
4055 @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
4056
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4057 @node else, Truth & Falsehood, if, Writing Defuns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4058 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4059 @section If--then--else Expressions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4060 @cindex Else
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 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
4063 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
4064 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
4065 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
4066 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
4067 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
4068 the beach, else read a book!''.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4069
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4070 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
4071 @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
4072 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
4073 indented less than the then-part:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4076 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4077 (if @var{true-or-false-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4078 @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
4079 @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
4080 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4081 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4082
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4083 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
4084 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
4085
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4086 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4087 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4088 (if (> 4 5) ; @r{if-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4089 (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
4090 (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
4091 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4092 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4093
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4094 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4095 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
4096 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
4097 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
4098 @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
4099
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4100 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
4101 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
4102 expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4103
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4104 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4105 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
4106 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
4107 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
4108 arguments to the function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4109
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4110 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4111 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4112 (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
4113 "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
4114 If the CHARACTERISTIC is the symbol `fierce',
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4115 then warn of a tiger;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4116 else say it's not fierce."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4117 (if (equal characteristic 'fierce)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4118 (message "It's a tiger!")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4119 (message "It's not fierce!")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4120 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4121 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4122 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4123
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4124 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4125 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4126 (type-of-animal 'fierce)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4127
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4128 (type-of-animal 'zebra)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4129
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4130 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4131 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4132
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4133 @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
4134 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4135 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
4136 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
4137 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
4138 @code{"It's not fierce!"}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4139
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4140 (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
4141 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
4142 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
4143 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
4144 write your program accordingly.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4145
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4146 @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
4147 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4148 @section Truth and Falsehood in Emacs Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4149 @cindex Truth and falsehood in Emacs Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4150 @cindex Falsehood and truth in Emacs Lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4151 @findex nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4152
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4153 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
4154 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
4155 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
4156 `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
4157 at all---is `true'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4158
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4159 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
4160 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
4161 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
4162 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
4163 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
4164 even a buffer!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4165
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4166 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4167 * nil explained:: @code{nil} has two meanings.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4168 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4169
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4170 @node nil explained, , Truth & Falsehood, Truth & Falsehood
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4171 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4172 @unnumberedsubsec An explanation of @code{nil}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4173 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4174
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4175 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
4176
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4177 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
4178 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
4179 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
4180 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
4181 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
4182 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
4183
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4184 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
4185 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
4186 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
4187 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
4188 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
4189 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
4190 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
4191 list, is returned by evaluating the expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4192
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4193 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
4194
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4195 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
4196 @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
4197 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
4198 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
4199 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
4200 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
4201
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4202 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4203 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4204 (if 4
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4205 'true
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4206 'false)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4207 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4208
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4209 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4210 (if nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4211 'true
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4212 'false)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4213 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4214 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4215
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4216 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4217 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
4218 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
4219 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
4220 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
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 (> 5 4)
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4227 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4228 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
4229
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4230 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4231 (> 4 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4232 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4233
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4234 @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
4235 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4236 @section @code{save-excursion}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4237 @findex save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4238 @cindex Region, what it is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4239 @cindex Preserving point, mark, and buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4240 @cindex Point, mark, buffer preservation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4241 @findex point
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4242 @findex mark
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4243
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4244 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
4245 that we will discuss in this chapter.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4246
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4247 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
4248 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
4249 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
4250 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
4251 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
4252 unexpected movement of point or mark.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4253
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4254 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4255 * 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
4256 * Template for save-excursion::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4257 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4258
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4259 @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
4260 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4261 @unnumberedsubsec Point and Mark
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4262 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4263
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4264 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
4265 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
4266 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
4267 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
4268 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
4269 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
4270 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
4271 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
4272 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
4273
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4274 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
4275 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
4276 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
4277 (@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
4278 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
4279 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
4280 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
4281 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
4282 times.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4283
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4284 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
4285 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
4286 @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
4287 @code{print-region}.
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 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
4290 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
4291 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
4292 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
4293 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
4294 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
4295 evaluated.
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 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
4298 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
4299 @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
4300 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
4301 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
4302 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
4303 @code{save-excursion} is good housekeeping.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4304
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4305 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
4306 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
4307 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
4308 abnormal exit''). This feature is very helpful.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4309
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4310 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
4311 @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
4312 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
4313 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
4314 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
4315 (@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
4316
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4317 @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
4318 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4319 @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
4320
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4321 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4322 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
4323
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4324 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4325 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4326 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4327 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4328 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4329 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4330
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4331 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4332 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
4333 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
4334 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
4335 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
4336 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
4337 @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
4338 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
4339
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4340 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4341 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
4342 looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4343
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4344 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4345 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4346 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4347 @var{first-expression-in-body}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4348 @var{second-expression-in-body}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4349 @var{third-expression-in-body}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4350 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4351 @var{last-expression-in-body})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4352 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4353 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4354
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4355 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4356 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
4357
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4358 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
4359 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
4360
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4361 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4362 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4363 (let @var{varlist}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4364 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4365 @var{body}@dots{}))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4366 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4367 @end smallexample
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 @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
4370 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4371 @section Review
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4372
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4373 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
4374 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
4375 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
4376
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4377 @table @code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4378 @item eval-last-sexp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4379 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
4380 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
4381 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
4382 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
4383
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4384 @item defun
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4385 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
4386 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
4387 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
4388 definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4389
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4390 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4391 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4392
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4393 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4394 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4395 (defun back-to-indentation ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4396 "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
4397 (interactive)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4398 (beginning-of-line 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4399 (skip-chars-forward " \t"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4400 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4401 @end smallexample
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 @item interactive
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4404 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
4405 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
4406 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
4407 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
4408 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
4409 newlines, @samp{\n}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4410
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4411 Common code characters are:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4412
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4413 @table @code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4414 @item b
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4415 The name of an existing buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4416
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4417 @item f
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4418 The name of an existing file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4419
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4420 @item p
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4421 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
4422
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4423 @item r
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4424 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
4425 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
4426 rather than one.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4427 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4428
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4429 @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
4430 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
4431 code characters.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4432
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4433 @item let
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4434 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
4435 @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
4436 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
4437 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
4438 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
4439 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
4440 @code{let}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4441
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4442 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4443 For example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4444
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4445 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4446 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4447 (let ((foo (buffer-name))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4448 (bar (buffer-size)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4449 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4450 "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
4451 foo bar))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4452 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4453 @end smallexample
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 @item save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4456 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
4457 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
4458 and mark and buffer afterward.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4459
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4460 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4461 For example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4462
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4463 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4464 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4465 (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
4466 (- (point)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4467 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4468 (goto-char (point-min)) (point))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4469 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4470 @end smallexample
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 @item if
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4473 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
4474 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
4475
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4476 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
4477 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
4478 commonly used.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4479
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4480 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4481 For example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4482
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4483 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4484 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4485 (if (string-equal
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4486 (number-to-string 21)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4487 (substring (emacs-version) 10 12))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4488 (message "This is version 21 Emacs")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4489 (message "This is not version 21 Emacs"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4490 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4491 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4492
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4493 @item equal
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4494 @itemx eq
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4495 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
4496 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
4497 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
4498 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
4499 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
4500 @findex equal
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4501 @findex eq
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4502
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4503 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4504 @item <
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4505 @itemx >
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4506 @itemx <=
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4507 @itemx >=
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4508 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
4509 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
4510 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
4511 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
4512 @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
4513 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
4514 (markers indicate positions in buffers).
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 @item string<
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4517 @itemx string-lessp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4518 @itemx string=
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4519 @itemx string-equal
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4520 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
4521 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
4522 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
4523
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4524 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
4525 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
4526 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
4527
42109
24f8e84cb04d Indexed `empty string' definition.
Robert J. Chassell <bob@rattlesnake.com>
parents: 42108
diff changeset
4528 @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
4529 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
4530 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
4531
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4532 @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
4533 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
4534 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
4535
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4536 @item message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4537 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
4538 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
4539 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
4540 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
4541 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
4542 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
4543
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4544 @item setq
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4545 @itemx set
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4546 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
4547 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
4548 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
4549 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
4550 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
4551 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
4552
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4553 @item buffer-name
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4554 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
4555
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4556 @itemx buffer-file-name
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4557 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
4558 visiting.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4559
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4560 @item current-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4561 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
4562 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
4563
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4564 @item other-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4565 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
4566 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
4567 buffer).
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 switch-to-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4570 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
4571 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
4572
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4573 @item set-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4574 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
4575 alter what the window is showing.
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 buffer-size
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4578 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
4579
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4580 @item point
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4581 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
4582 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
4583 buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4584
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4585 @item point-min
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4586 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
4587 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
4588
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4589 @item point-max
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4590 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
4591 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
4592 effect.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4593 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4594
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4595 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4596 @node defun Exercises, , Review, Writing Defuns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4597 @section Exercises
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4598
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4599 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4600 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4601 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
4602 argument, a number. Make that function interactive.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4603
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4604 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4605 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
4606 @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
4607 and if so, prints an appropriate message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4608 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4609
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4610 @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
4611 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4612 @chapter A Few Buffer--Related 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 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
4615 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
4616 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
4617 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
4618 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
4619 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
4620 buffers. Later, we will study other functions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4621
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4622 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4623 * Finding More:: How to find more information.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4624 * 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
4625 @code{point-min}, and @code{push-mark}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4626 * 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
4627 * 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
4628 @code{insert-buffer-substring}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4629 * Buffer Related Review:: Review.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4630 * Buffer Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4631 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4632
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4633 @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
4634 @section Finding More Information
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4635
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4636 @findex describe-function, @r{introduced}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4637 @cindex Find function documentation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4638 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
4639 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
4640 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
4641 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
4642 @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
4643 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
4644 then @key{RET}).
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 @cindex Find source of function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4647 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
4648 @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
4649 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
4650 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
4651 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
4652 definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4653
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4654 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
4655 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
4656 @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
4657 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
4658 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
4659 Texinfo source file of this document.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4660
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4661 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
4662 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
4663 @code{find-tags} jumps.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4664
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4665 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
4666 @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
4667 @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
4668 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
4669 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
4670 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
4671 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
4672 @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
4673 @key{ALT}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4674
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4675 @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
4676 @cindex TAGS table, specifying
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4677 @findex find-tags
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4678 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
4679 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
4680 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
4681 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
4682 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
4683 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
4684 @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
4685 @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
4686 @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
4687 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
4688
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4689 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4690 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
4691 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
4692 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
4693 @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
4694
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4695 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4696 M-x compile RET etags *.el RET
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4697 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4698
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4699 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
4700
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4701 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
4702 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
4703 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
4704
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4705 @cindex Library, as term for `file'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4706 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
4707 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
4708 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
4709 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
4710 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
4711 @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
4712 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
4713 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
4714 @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
4715 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
4716 @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
4717 by topic keywords.''
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4718
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4719 @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
4720 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4721 @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
4722 @findex simplified-beginning-of-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4723
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4724 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
4725 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
4726 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
4727 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
4728 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
4729
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4730 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
4731 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
4732 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
4733 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
4734 (@xref{beginning-of-buffer, , Complete Definition of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4735 @code{beginning-of-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 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
4738 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
4739 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
4740 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
4741 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
4742 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
4743 of the buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4744
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4745 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4746 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
4747
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4748 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4749 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4750 (defun simplified-beginning-of-buffer ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4751 "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
4752 leave mark at previous position."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4753 (interactive)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4754 (push-mark)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4755 (goto-char (point-min)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4756 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4757 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4758
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4759 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
4760 the special form @code{defun}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4761
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4762 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4763 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4764 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
4765
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4766 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4767 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
4768
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4769 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4770 The documentation string.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4771
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4772 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4773 The interactive expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4774
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4775 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4776 The body.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4777 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4778
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4779 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4780 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
4781 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
4782 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
4783 an optional argument.)
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 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
4786 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
4787 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
4788 require one.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4789
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4790 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4791 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
4792
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4793 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4794 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4795 (push-mark)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4796 (goto-char (point-min))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4797 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4798 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4799
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4800 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
4801 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
4802 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
4803 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
4804
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4805 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
4806 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
4807 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
4808 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
4809 Narrowing and Widening}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4810
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4811 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
4812 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
4813 @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
4814 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
4815
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4816 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
4817
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4818 @findex describe-function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4819 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
4820 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
4821 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
4822 @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
4823 @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
4824 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
4825 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
4826
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4827 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4828 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4829 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
4830 Beginning of buffer is position (point-min),
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4831 end is (point-max).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4832 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4833 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4834
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4835 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4836 (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
4837 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
4838 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
4839 @key{RET}}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4840
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4841 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
4842 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
4843 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
4844 of @code{(goto-char (point-min))}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4845
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4846 @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
4847 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4848 @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
4849 @findex mark-whole-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4850
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4851 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
4852 @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
4853 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
4854
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4855 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
4856 @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
4857 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
4858 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
4859 h}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4860
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4861
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4862 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4863 * mark-whole-buffer overview::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4864 * 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
4865 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4866
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 @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
4869 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4870 @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
4871 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4872
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4873 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4874 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
4875
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4876 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4877 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4878 (defun mark-whole-buffer ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4879 "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
4880 (interactive)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4881 (push-mark (point))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4882 (push-mark (point-max))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4883 (goto-char (point-min)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4884 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4885 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4886
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4887 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4888 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
4889 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
4890 this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4891
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4892 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4893 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4894 (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
4895 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4896 (@var{interactive-expression}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4897 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4898 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4899 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4900
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4901 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
4902 @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
4903 @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
4904 The documentation comes next.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4905
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4906 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
4907 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
4908 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
4909 previous section.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4910
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4911 @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
4912 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4913 @subsection Body of @code{mark-whole-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4914
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4915 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
4916 lines of code:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4919 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4920 (push-mark (point))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4921 (push-mark (point-max))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4922 (goto-char (point-min))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4923 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4924 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4925
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4926 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
4927
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4928 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
4929 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
4930 @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
4931 at the current position of the cursor.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4932
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4933 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
4934 @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
4935 @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
4936 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
4937 @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
4938 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
4939 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
4940 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
4941 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
4942 there.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4943
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4944 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
4945 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
4946 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
4947 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
4948 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
4949 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
4950 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
4951 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
4952 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
4953 @kbd{C-u C-@key{SPC}} twice.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4954
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4955 (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
4956 complicated than shown here. The line reads
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4957
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4958 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4959 (push-mark (point-max) nil t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4960 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4961
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4962 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4963 (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
4964 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
4965 this version, @code{push-mark} has two additional arguments. The
2a4f1d831675 Fixed typographic error.
Robert J. Chassell <bob@rattlesnake.com>
parents: 41674
diff changeset
4966 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
4967 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
4968 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
4969 @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
4970 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
4971 region. It is usually turned off.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4972
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4973 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
4974 (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
4975 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
4976 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
4977 (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
4978 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
4979 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
4980 region.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4981
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4982 @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
4983 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4984 @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
4985 @findex append-to-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4986
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4987 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
4988 @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
4989 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
4990 buffer to a specified buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4991
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4992 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4993 * append-to-buffer overview::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4994 * append interactive:: A two part interactive expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4995 * 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
4996 * 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
4997 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4998
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
4999 @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
5000 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5001 @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
5002 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5003
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5004 @findex insert-buffer-substring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5005 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
5006 @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
5007 @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
5008 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
5009 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
5010 concerned with setting up the conditions for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5011 @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
5012 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
5013 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
5014
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5015 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5016 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5017 (defun append-to-buffer (buffer start end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5018 "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
5019 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
5020 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5021
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5022 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5023 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
5024 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
5025 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
5026 (interactive "BAppend to buffer:@: \nr")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5027 (let ((oldbuf (current-buffer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5028 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5029 (set-buffer (get-buffer-create buffer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5030 (insert-buffer-substring oldbuf start end))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5031 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5032 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5033
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5034 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
5035 filled-in templates.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5036
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5037 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
5038 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
5039
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5040 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5041 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5042 (defun append-to-buffer (buffer start end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5043 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5044 (interactive "BAppend to buffer:@: \nr")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5045 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5046 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5047 @end smallexample
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 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
5050 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
5051 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
5052 will be copied.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5053
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5054 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
5055 complete.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5056
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5057 @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
5058 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5059 @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
5060
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5061 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
5062 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
5063 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
5064 Function Interactive}.) The expression reads as follows:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5067 (interactive "BAppend to buffer:@: \nr")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5068 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5069
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5070 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5071 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
5072 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
5073
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5074 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
5075 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
5076 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
5077 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
5078 @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
5079 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
5080
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5081 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
5082 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
5083 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
5084 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
5085 point and mark.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5086
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5087 @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
5088 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5089 @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
5090
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5091 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
5092
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5093 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
5094 @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
5095 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
5096 @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
5097 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
5098
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5099 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
5100 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
5101 @code{let} expression in outline:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5102
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5103 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5104 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5105 (defun append-to-buffer (buffer start end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5106 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5107 (interactive "BAppend to buffer:@: \nr")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5108 (let ((@var{variable} @var{value}))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5109 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5110 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5111 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5112
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5113 The @code{let} expression has three elements:
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 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5116 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5117 The symbol @code{let};
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 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5120 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
5121 @code{(@var{variable} @var{value})};
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5122
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5123 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5124 The body of the @code{let} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5125 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5126
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5127 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5128 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
5129
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5130 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5131 (oldbuf (current-buffer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5132 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5133
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5134 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5135 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
5136 @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
5137 @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
5138 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
5139 which you will copy.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5140
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5141 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
5142 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
5143 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
5144 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
5145 The line looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5146
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5147 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5148 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5149 (let ((oldbuf (current-buffer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5150 @dots{} )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5151 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5152 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5153
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5154 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5155 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
5156 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
5157 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
5158 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
5159
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5160 @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
5161 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5162 @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
5163
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5164 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
5165 consists of a @code{save-excursion} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5166
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5167 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
5168 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
5169 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
5170 @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
5171 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
5172 @code{append-to-buffer}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5173
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5174 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5175 @cindex Indentation for formatting
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5176 @cindex Formatting convention
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5177 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
5178 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
5179 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
5180 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
5181 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
5182 this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5183
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5184 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5185 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5186 (defun @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5187 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5188 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5189 (let@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5190 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5191 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5192 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5193 @end smallexample
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 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5196 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5197 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
5198 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
5199 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
5200 @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
5201 with the @code{let}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5202
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5203 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5204 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5205 (let ((oldbuf (current-buffer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5206 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5207 (set-buffer (get-buffer-create buffer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5208 (insert-buffer-substring oldbuf start end))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5209 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5210 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5211
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5212 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5213 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
5214 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
5215
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5216 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5217 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5218 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5219 @var{first-expression-in-body}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5220 @var{second-expression-in-body}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5221 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5222 @var{last-expression-in-body})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5223 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5224 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5225
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5226 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5227 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5228 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
5229 two expressions. The body looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5230
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5231 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5232 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5233 (set-buffer (get-buffer-create buffer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5234 (insert-buffer-substring oldbuf start end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5235 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5236 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5237
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5238 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
5239 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
5240 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
5241 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
5242 only for its side effects.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5243
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5244 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
5245 @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
5246 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
5247 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
5248 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
5249 primary work of the function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5251 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
5252 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
5253 return.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5254
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5255 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5256 The line looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5257
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5258 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5259 (set-buffer (get-buffer-create buffer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5260 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5261
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5262 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
5263 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
5264 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
5265 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
5266 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
5267
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5268 @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
5269 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
5270 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
5271 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
5272 @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
5273
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5274 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5275 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
5276 the text:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5277
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5278 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5279 (insert-buffer-substring oldbuf start end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5280 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5283 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
5284 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
5285 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
5286 @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
5287 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
5288 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
5289
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5290 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
5291 @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
5292 @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
5293
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5294 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5295 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
5296
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5297 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5298 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5299 (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
5300 (save-excursion ; @r{Keep track of buffer.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5301 @var{change-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5302 @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
5303
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5304 @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
5305 @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
5306
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5307 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5308 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5309
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5310 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
5311 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
5312 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
5313 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
5314 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
5315 brings you back to your original buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5316
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5317 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
5318 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
5319 @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
5320 buffer. Many function definitions use @code{let},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5321 @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
5322
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5323 @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
5324 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5325 @section Review
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 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
5328
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5329 @table @code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5330 @item describe-function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5331 @itemx describe-variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5332 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
5333 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
5334
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5335 @item find-tag
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5336 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
5337 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
5338 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
5339 @key{META} key).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5340
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5341 @item save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5342 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
5343 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
5344 the current buffer and return to it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5345
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5346 @item push-mark
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5347 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
5348 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
5349 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
5350
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5351 @item goto-char
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5352 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
5353 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
5354 a position, such as @code{(point-min)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5355
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5356 @item insert-buffer-substring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5357 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
5358 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
5359
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5360 @item mark-whole-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5361 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
5362
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5363 @item set-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5364 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
5365 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
5366 to work on a different buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5367
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5368 @item get-buffer-create
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5369 @itemx get-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5370 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
5371 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
5372 buffer does not exist.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5373 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5374
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5375 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5376 @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
5377 @section Exercises
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5378
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5379 @itemize @bullet
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 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
5382 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
5383
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5384 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5385 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
5386 message telling you whether a buffer exists.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5387
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5388 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5389 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
5390 function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5391 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5392
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5393 @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
5394 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5395 @chapter A Few More Complex Functions
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 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
5398 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
5399 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
5400 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
5401 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
5402 @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
5403 to which the name refers.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5404
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5405 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5406 * 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
5407 * 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
5408 * beginning-of-buffer:: Shows @code{goto-char},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5409 @code{point-min}, and @code{push-mark}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5410 * Second Buffer Related Review::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5411 * optional Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5412 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5413
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5414 @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
5415 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5416 @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
5417 @findex copy-to-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5418
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5419 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
5420 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
5421 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
5422 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
5423 @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
5424 @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
5425 @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
5426 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
5427 @code{append-to-buffer}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5428
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5429 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5430 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
5431
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5432 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5433 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5434 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5435 (interactive "BCopy to buffer:@: \nr")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5436 (let ((oldbuf (current-buffer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5437 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5438 (set-buffer (get-buffer-create buffer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5439 (erase-buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5440 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5441 (insert-buffer-substring oldbuf start end)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5442 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5443 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5444
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5445 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
5446 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
5447 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
5448 @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
5449 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
5450 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
5451 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
5452 @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
5453 inserted.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5454
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5455 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
5456 function does.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5457
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5458 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5459 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
5460
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5461 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5462 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5463 (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
5464 (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
5465 @var{change-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5466 (erase-buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5467 (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
5468 @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
5469 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5470 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5471
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5472 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
5473 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
5474 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
5475 @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
5476 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
5477 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
5478 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
5479 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
5480 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
5481 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
5482 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
5483 nicety.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5484
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5485 @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
5486 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5487 @section The Definition of @code{insert-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5488 @findex insert-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5489
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5490 @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
5491 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
5492 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
5493 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
5494
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5495 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
5496 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
5497 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
5498
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5499 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5500 * insert-buffer code::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5501 * 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
5502 * 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
5503 * 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
5504 * 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
5505 * Insert let:: Two @code{save-excursion} expressions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5506 @end menu
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 @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
5509 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5510 @unnumberedsubsec The Code for @code{insert-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5511 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5512
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5513 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5514 Here is the code:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5515
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5516 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5517 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5518 (defun insert-buffer (buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5519 "Insert after point the contents of BUFFER.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5520 Puts mark after the inserted text.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5521 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
5522 (interactive "*bInsert buffer:@: ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5523 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5524 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5525 (or (bufferp buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5526 (setq buffer (get-buffer buffer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5527 (let (start end newmark)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5528 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5529 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5530 (set-buffer buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5531 (setq start (point-min) end (point-max)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5532 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5533 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5534 (insert-buffer-substring buffer start end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5535 (setq newmark (point)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5536 (push-mark newmark)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5537 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5538 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5539
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5540 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5541 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
5542 outline of the function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5543
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5544 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5545 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5546 (defun insert-buffer (buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5547 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5548 (interactive "*bInsert buffer:@: ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5549 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5550 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5551 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5552
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5553 @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
5554 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5555 @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
5556 @findex interactive, @r{example use of}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5557
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5558 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
5559 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
5560 buffer:@: }.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5561
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5562 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5563 * 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
5564 * 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
5565 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5566
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5567 @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
5568 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5569 @unnumberedsubsubsec A Read-only Buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5570 @cindex Read-only buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5571 @cindex Asterisk for read-only buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5572 @findex * @r{for read-only buffer}
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 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
5575 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
5576 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
5577 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
5578 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
5579 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
5580 the next argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5581
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5582 @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
5583 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5584 @unnumberedsubsubsec @samp{b} in an Interactive Expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5585
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5586 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
5587 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
5588 @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
5589 @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
5590 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
5591 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
5592 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
5593 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
5594 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
5595 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
5596 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
5597
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5598 @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
5599 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5600 @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
5601
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5602 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
5603 @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
5604 @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
5605 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
5606 @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
5607 into the current buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5608
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5609 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5610 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
5611 function like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5612
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5613 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5614 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5615 (defun insert-buffer (buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5616 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5617 (interactive "*bInsert buffer:@: ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5618 (or @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5619 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5620 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5621 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5622 (let (@var{varlist})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5623 @var{body-of-}@code{let}@dots{} )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5624 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5625 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5626
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5627 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
5628 @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
5629 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
5630
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5631 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
5632 @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
5633
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5634 @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
5635 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5636 @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
5637
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5638 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
5639 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
5640 then the buffer itself must be got.
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 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
5643 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
5644 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
5645 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
5646
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5647 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5648 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
5649
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5650 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5651 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5652 (if (not (holding-on-to-guest))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5653 (find-and-take-arm-of-guest))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5654 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5655 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5656
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5657 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
5658 buffer itself, we want to get it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5659
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5660 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5661 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
5662 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
5663
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5664 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5665 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5666 (if (not (bufferp buffer)) ; @r{if-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5667 (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
5668 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5669 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5670
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5671 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5672 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
5673 @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
5674 @w{@code{(setq buffer (get-buffer buffer))}}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5675
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5676 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
5677 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
5678 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
5679 @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
5680 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
5681 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
5682 @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
5683 Argument}.)
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 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5686 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
5687 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
5688
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5689 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5690 (not (bufferp buffer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5691 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5692
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5693 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5694 @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
5695 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
5696 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
5697 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
5698
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5699 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
5700 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
5701 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
5702 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
5703 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
5704 a buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5705
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5706 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
5707 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
5708 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
5709 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
5710 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
5711 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
5712 @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
5713 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
5714
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5715 @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
5716 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5717 @subsection The @code{or} in the Body
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5718
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5719 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
5720 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
5721 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
5722 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
5723 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
5724 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
5725
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5726 @findex or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5727 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
5728 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
5729 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
5730 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
5731 returning the first non-@code{nil} value.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5732
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5733 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5734 The @code{or} expression looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5735
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5736 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5737 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5738 (or (bufferp buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5739 (setq buffer (get-buffer buffer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5740 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5741 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5742
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5743 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5744 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
5745 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
5746 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
5747 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
5748 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
5749 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
5750 @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
5751
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5752 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
5753 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
5754 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
5755 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
5756 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
5757 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
5758 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
5759
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5760 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
5761 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
5762 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
5763 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
5764 buffer.
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5767 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
5768 written like this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5771 (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
5772 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5773
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5774 @node Insert let, , Insert or, insert-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5775 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5776 @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
5777
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5778 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
5779 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
5780 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
5781 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
5782 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
5783 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
5784 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
5785
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5786 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5787 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
5788 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
5789 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
5790
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5791 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5792 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5793 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5794 (set-buffer buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5795 (setq start (point-min) end (point-max)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5796 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5797 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5798
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5799 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5800 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
5801 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
5802 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
5803 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
5804 @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
5805 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
5806 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
5807 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
5808 fourth.
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 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
5811 @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
5812 @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
5813 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
5814
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5815 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5816 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
5817
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5818 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5819 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5820 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5821 (@var{inner-}@code{save-excursion}@var{-expression}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5822 (@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
5823 (insert-buffer-substring buffer start end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5824 (setq newmark (point)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5825 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5826 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5827
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5828 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5829 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
5830 @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
5831 @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
5832 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
5833 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
5834 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
5835 recorded in the variable @code{newmark}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5836
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5837 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
5838 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
5839
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5840 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
5841 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
5842 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
5843 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
5844 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
5845 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
5846 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
5847 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
5848 before you called the insert function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5849
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5850 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5851 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
5852
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5853 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5854 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5855 (let (start end newmark)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5856 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5857 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5858 (set-buffer buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5859 (setq start (point-min) end (point-max)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5860 (insert-buffer-substring buffer start end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5861 (setq newmark (point)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5862 (push-mark newmark))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5863 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5864 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5865
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5866 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
5867 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
5868 @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
5869 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
5870 find and use again and again.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5871
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5872 @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
5873 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5874 @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
5875 @findex beginning-of-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5876
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5877 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
5878 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
5879 Simplified @code{beginning-of-buffer} Definition}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5880 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
5881
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5882 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
5883 @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
5884 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
5885 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
5886 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
5887 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
5888 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
5889 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
5890 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
5891 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
5892 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
5893 to the end of the buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5894
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5895 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
5896 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
5897
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5898 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5899 * Optional Arguments::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5900 * 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
5901 * beginning-of-buffer complete::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5902 @end menu
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 @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
5905 @subsection Optional Arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5906
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5907 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
5908 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
5909 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
5910 @samp{Wrong number of arguments}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5911
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5912 @cindex Optional arguments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5913 @cindex Keyword
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5914 @findex optional
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5915 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
5916 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
5917 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
5918 @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
5919 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
5920 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
5921
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5922 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5923 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
5924 therefore looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5925
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5926 @smallexample
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 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5929
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5930 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5931 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
5932
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5933 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5934 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5935 (defun beginning-of-buffer (&optional arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5936 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5937 (interactive "P")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5938 (push-mark)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5939 (goto-char
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5940 (@var{if-there-is-an-argument}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5941 @var{figure-out-where-to-go}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5942 @var{else-go-to}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5943 (point-min))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5944 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5945 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5946
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5947 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
5948 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
5949 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
5950 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
5951 there is an argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5952
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5953 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
5954 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
5955 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
5956 @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
5957 defaults to 4).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5958
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5959 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
5960 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
5961 @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
5962 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
5963 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
5964 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
5965 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
5966 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
5967 @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
5968 @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
5969 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
5970 form.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5971
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5972 @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
5973 @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
5974
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5975 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
5976 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
5977 @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
5978 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
5979 like this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5982 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5983 (if (> (buffer-size) 10000)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5984 ;; @r{Avoid overflow for large buffer sizes!}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5985 (* (prefix-numeric-value arg) (/ (buffer-size) 10))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5986 (/
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5987 (+ 10
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5988 (*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5989 (buffer-size) (prefix-numeric-value arg))) 10))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5990 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5991 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5992
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5993 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5994 * Disentangle beginning-of-buffer::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5995 * Large buffer case::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5996 * Small buffer case::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5997 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5998
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
5999 @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
6000 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6001 @unnumberedsubsubsec Disentangle @code{beginning-of-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6002 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6003
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6004 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
6005 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
6006 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
6007 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
6008
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6009 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6010 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6011 (if (@var{buffer-is-large}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6012 @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
6013 @var{else-use-alternate-calculation}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6014 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6015 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6016
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6017 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
6018 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
6019 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
6020 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
6021 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
6022 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
6023 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
6024 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
6025 far larger than ever before.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6026
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6027 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
6028
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6029 @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
6030 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6031 @unnumberedsubsubsec What happens in a large buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6032
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6033 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
6034 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
6035 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
6036
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6037 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6038 The line looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6039
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6040 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6041 (if (> (buffer-size) 10000)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6042 @end smallexample
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 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6045 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6046 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
6047 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
6048
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6049 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6050 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6051 (*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6052 (prefix-numeric-value arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6053 (/ (buffer-size) 10))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6054 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6055 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6056
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6057 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6058 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
6059 @code{*}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6060
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6061 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
6062 @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
6063 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
6064 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
6065 the arithmetic, a conversion is necessary, and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6066 @code{prefix-numeric-value} does the job.
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 @findex / @r{(division)}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6069 @cindex Division
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6070 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
6071 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
6072 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
6073 (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
6074 used for multiplication.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6075
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6076 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6077 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
6078 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
6079
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6080 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6081 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6082 (* @var{numeric-value-of-prefix-arg}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6083 @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
6084 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6085 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6086
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6087 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6088 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
6089 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
6090 buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6091
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6092 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6093 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
6094 @code{goto-char} expression reads like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6095
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6096 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6097 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6098 (goto-char (* (prefix-numeric-value arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6099 (/ (buffer-size) 10)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6100 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6101 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6102
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6103 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
6104
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6105 @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
6106 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6107 @unnumberedsubsubsec What happens in a small buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6108
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6109 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
6110 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
6111 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
6112 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
6113 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
6114
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6115 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6116 The code looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6117
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6118 @c Keep this on one line.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6119 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6120 (/ (+ 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
6121 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6122
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6123 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6124 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6125 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
6126 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
6127 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
6128 enclosing expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6129
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6130 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6131 @group
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 (+ 10
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6134 (*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6135 (buffer-size)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6136 (prefix-numeric-value arg)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6137 10))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6138 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6139 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6140
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6141 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6142 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6143 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
6144 @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
6145 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
6146 expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6147
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6148 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6149 (* (buffer-size) (prefix-numeric-value arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6150 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6151
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6152 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6153 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
6154 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
6155 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
6156 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
6157 position in the buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6158
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6159 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
6160 the cursor is moved to that point.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6161
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6162 @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
6163 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6164 @subsection The Complete @code{beginning-of-buffer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6165
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6166 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6167 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
6168
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6169 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6170 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6171 (defun beginning-of-buffer (&optional arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6172 "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
6173 leave mark at previous position.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6174 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
6175 from the true beginning.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6176 Don't use this in Lisp programs!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6177 \(goto-char (point-min)) is faster
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6178 and does not set the mark."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6179 (interactive "P")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6180 (push-mark)
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 (goto-char
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6184 (if arg
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6185 (if (> (buffer-size) 10000)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6186 ;; @r{Avoid overflow for large buffer sizes!}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6187 (* (prefix-numeric-value arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6188 (/ (buffer-size) 10))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6189 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6190 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6191 (/ (+ 10 (* (buffer-size)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6192 (prefix-numeric-value arg)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6193 10))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6194 (point-min)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6195 (if arg (forward-line 1)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6196 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6197 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6198
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6199 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6200 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
6201 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
6202 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
6203 the function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6204
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6205 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6206 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
6207
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6208 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6209 \(goto-char (point-min))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6210 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6211
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6212 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6213 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
6214 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
6215 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
6216 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
6217
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6218 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6219 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
6220 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
6221 invoked with an argument:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6222
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6223 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6224 (if arg (forward-line 1)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6225 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6228 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
6229 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
6230 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
6231 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
6232 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
6233 draw complaints.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6234
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6235 @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
6236 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6237 @section Review
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6238
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6239 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
6240
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6241 @table @code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6242 @item or
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6243 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
6244 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
6245 @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
6246 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
6247 other are true.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6248
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6249 @item and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6250 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
6251 @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
6252 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
6253 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
6254 true.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6255
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6256 @item &optional
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6257 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
6258 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
6259 argument, if desired.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6260
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6261 @item prefix-numeric-value
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6262 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
6263 "P")} to a numeric value.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6264
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6265 @item forward-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6266 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
6267 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
6268 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
6269 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
6270 supposed to move but couldn't.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6271
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6272 @item erase-buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6273 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
6274
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6275 @item bufferp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6276 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
6277 @end table
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 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
6280 @section @code{optional} Argument Exercise
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6281
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6282 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
6283 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
6284 @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
6285 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
6286
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6287 @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
6288 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6289 @chapter Narrowing and Widening
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6290 @cindex Focusing attention (narrowing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6291 @cindex Narrowing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6292 @cindex Widening
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6293
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6294 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
6295 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
6296 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
6297 novices.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6298
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6299 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6300 * Narrowing advantages:: The advantages of narrowing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6301 * 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
6302 * 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
6303 * narrow Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6304 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6305
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6306 @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
6307 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6308 @unnumberedsec The Advantages of Narrowing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6309 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6310
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6311 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
6312 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
6313 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
6314 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
6315 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
6316 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
6317 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
6318 narrowing just to the region you want.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6319 (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
6320
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6321 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
6322 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
6323 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
6324 (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
6325 (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
6326 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
6327 @code{widen} command.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6328 (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
6329
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6330 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
6331 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
6332 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
6333 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
6334 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
6335 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
6336 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
6337 @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
6338 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
6339 situation.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6340
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6341 @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
6342 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6343 @section The @code{save-restriction} Special Form
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6344 @findex save-restriction
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6345
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6346 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
6347 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
6348 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
6349 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
6350 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
6351 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
6352 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
6353 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
6354 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
6355 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
6356 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
6357 function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6358
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6359 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6360 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
6361
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6362 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6363 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6364 (save-restriction
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6365 @var{body}@dots{} )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6366 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6367 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6368
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6369 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6370 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
6371 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
6372
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6373 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
6374 @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
6375 @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
6376 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
6377 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
6378 @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
6379 like this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6382 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6383 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6384 (save-restriction
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6385 @var{body}@dots{}))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6386 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6387 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6388
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6389 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
6390 @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
6391 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
6392
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6393 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6394 For example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6395
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6396 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6397 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6398 (save-restriction
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6399 (widen)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6400 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6401 @var{body}@dots{}))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6402 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6403 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6404
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6405 @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
6406 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6407 @section @code{what-line}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6408 @findex what-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6409 @cindex Widening, example of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6410
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6411 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
6412 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
6413 @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
6414 text of the function in full:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6415
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6416 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6417 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6418 (defun what-line ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6419 "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
6420 (interactive)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6421 (save-restriction
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6422 (widen)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6423 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6424 (beginning-of-line)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6425 (message "Line %d"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6426 (1+ (count-lines 1 (point)))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6427 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6428 @end smallexample
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 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
6431 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
6432 @code{widen}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6433
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6434 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
6435 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
6436 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
6437
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6438 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
6439 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
6440 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
6441 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
6442 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
6443 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
6444 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
6445 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
6446 @code{save-restriction} special form.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6447
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6448 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
6449 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
6450 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
6451 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
6452
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6453 (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
6454 @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
6455 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
6456 @code{save-excursion} outermost.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6457
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6458 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6459 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
6460 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
6461 echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6462
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6463 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6464 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6465 (message "Line %d"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6466 (1+ (count-lines 1 (point)))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6467 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6468 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6469
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6470 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
6471 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
6472 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
6473 @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
6474 @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
6475 something such as @samp{Line 243}.
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 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6478 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
6479 last line of the function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6480
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6481 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6482 (1+ (count-lines 1 (point)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6483 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6486 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
6487 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
6488 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
6489 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
6490 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
6491 current line.
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 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
6494 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
6495 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
6496 the original narrowing, if any.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6497
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6498 @node narrow Exercise, , what-line, Narrowing & Widening
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6499 @section Exercise with Narrowing
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 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
6502 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
6503 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
6504 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
6505 @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
6506 @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
6507 functions, a whole potpourri.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6508
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6509 @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
6510 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6511 @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
6512 @findex car, @r{introduced}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6513 @findex cdr, @r{introduced}
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 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
6516 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
6517 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
6518
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6519 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
6520 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
6521 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
6522
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6523 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6524 * 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
6525 * 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
6526 * cons:: Constructing a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6527 * nthcdr:: Calling @code{cdr} repeatedly.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6528 * nth::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6529 * 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
6530 * setcdr:: Changing the rest of a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6531 * cons Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6532 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6533
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6534 @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
6535 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6536 @unnumberedsec Strange Names
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6537 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6538
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6539 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
6540 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
6541 @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
6542 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
6543 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
6544 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
6545 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
6546 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
6547 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
6548 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
6549 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
6550 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
6551 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
6552 introduction.
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 @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
6555 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6556 @section @code{car} and @code{cdr}
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 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
6559 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
6560 @code{rose}.
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 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6563 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
6564 evaluating the following:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6567 (car '(rose violet daisy buttercup))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6568 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6569
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6570 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6571 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
6572 area.
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 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
6575 @code{first} and this is often suggested.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6576
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6577 @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
6578 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
6579 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
6580 `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
6581
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6582 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
6583 @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
6584 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
6585 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
6586 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
6587 buttercup)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6588
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6589 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6590 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
6591
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6592 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6593 (cdr '(rose violet daisy buttercup))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6594 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6597 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
6598 the echo area.
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 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
6601 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
6602 elements are.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6603
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6604 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
6605 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
6606 @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
6607
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6608 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
6609
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6610 (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
6611 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
6612 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
6613 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
6614 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
6615 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
6616 after you will be grateful to you.)
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 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
6619 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
6620 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
6621 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
6622 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
6623 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
6624 the usual way:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6627 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6628 (car '(pine fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6629
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6630 (cdr '(pine fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6631 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6632 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6633
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6634 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
6635 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
6636 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
6637 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
6638
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6639 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6640 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6641 (car '((lion tiger cheetah)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6642 (gazelle antelope zebra)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6643 (whale dolphin seal)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6644 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6645 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6646
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6647 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6648 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
6649 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
6650 @code{((gazelle antelope zebra) (whale dolphin seal))}.
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6653 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6654 (cdr '((lion tiger cheetah)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6655 (gazelle antelope zebra)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6656 (whale dolphin seal)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6657 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6658 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6659
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6660 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
6661 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
6662 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
6663
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6664 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
6665 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
6666 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
6667 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
6668 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
6669 @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
6670 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
6671 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
6672 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
6673 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
6674 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
6675 Emacs Lisp Reference Manual}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6676
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6677 @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
6678 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6679 @section @code{cons}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6680 @findex cons, @r{introduced}
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 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
6683 @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
6684 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
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 (cons '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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6691 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6692 After evaluating this list, you will see
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6695 (pine fir oak maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6696 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6697
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6698 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6699 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
6700 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
6701
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6702 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6703 * Build a list::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6704 * 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
6705 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6706
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6707 @node Build a list, length, cons, cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6708 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6709 @unnumberedsubsec Build a list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6710 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6711
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6712 @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
6713 @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
6714 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
6715 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
6716 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
6717 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
6718 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
6719 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
6720 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
6721 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
6722
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6723 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6724 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6725 (cons 'buttercup ())
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6726 @result{} (buttercup)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6727 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6728
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6729 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6730 (cons 'daisy '(buttercup))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6731 @result{} (daisy buttercup)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6732 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6733
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6734 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6735 (cons 'violet '(daisy buttercup))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6736 @result{} (violet daisy buttercup)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6737 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6738
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6739 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6740 (cons 'rose '(violet daisy buttercup))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6741 @result{} (rose violet daisy buttercup)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6742 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6743 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6746 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
6747 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
6748 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
6749 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
6750 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
6751 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
6752
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6753 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
6754 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
6755 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
6756 @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
6757
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6758 @node length, , Build a list, cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6759 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6760 @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
6761 @findex length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6762
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6763 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
6764 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
6765
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6766 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6767 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6768 (length '(buttercup))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6769 @result{} 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6770 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6771
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6772 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6773 (length '(daisy buttercup))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6774 @result{} 2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6775 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6776
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6777 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6778 (length (cons 'violet '(daisy buttercup)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6779 @result{} 3
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6780 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6781 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6782
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6783 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6784 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
6785 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
6786 its argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6787
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6788 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6789 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
6790 empty list:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6791
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6792 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6793 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6794 (length ())
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6795 @result{} 0
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6796 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6797 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6798
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6799 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6800 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
6801
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6802 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
6803 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
6804 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
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 (length )
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6811 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6812 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
6813
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6814 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6815 Wrong number of arguments: #<subr length>, 0
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6816 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6817
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6818 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6819 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
6820 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
6821 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
6822 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
6823 @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
6824
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6825 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
6826 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
6827 @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
6828 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
6829 (@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
6830 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
6831 Manual}, for more about subroutines.
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 @node nthcdr, nth, cons, car cdr & cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6834 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6835 @section @code{nthcdr}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6836 @findex nthcdr
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6837
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6838 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
6839 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
6840
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6841 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
6842 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
6843 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
6844 @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
6845 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
6846 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
6847 @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
6848 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
6849 @code{()} is shown as @code{nil}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6850
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6851 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6852 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
6853 the @samp{@result{}} shows what is returned.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6854
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6855 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6856 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6857 (cdr '(pine fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6858 @result{}(fir oak maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6859 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6860
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6861 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6862 (cdr '(fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6863 @result{} (oak maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6864 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6865
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6866 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6867 (cdr '(oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6868 @result{}(maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6869 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6870
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6871 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6872 (cdr '(maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6873 @result{} nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6874 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6875
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6876 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6877 (cdr 'nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6878 @result{} nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6879 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6880
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6881 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6882 (cdr ())
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6883 @result{} nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6884 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6885 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6886
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6887 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6888 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
6889 between, like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6890
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6891 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6892 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6893 (cdr (cdr '(pine fir oak maple)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6894 @result{} (oak maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6895 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6896 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6897
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6898 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6899 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
6900 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
6901 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
6902 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
6903 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
6904 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
6905 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
6906 first two elements.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6907
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6908 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
6909 @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
6910 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
6911 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
6912 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
6913
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6914 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6915 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6916 (nthcdr 2 '(pine fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6917 @result{} (oak maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6918 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6919 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6920
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6921 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6922 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
6923 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
6924 and 5:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6925
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6926 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6927 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6928 ;; @r{Leave the list as it was.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6929 (nthcdr 0 '(pine fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6930 @result{} (pine fir oak maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6931 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6932
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6933 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6934 ;; @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
6935 (nthcdr 1 '(pine fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6936 @result{} (fir oak maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6937 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6938
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6939 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6940 ;; @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
6941 (nthcdr 3 '(pine fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6942 @result{} (maple)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6943 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6944
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6945 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6946 ;; @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
6947 (nthcdr 4 '(pine fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6948 @result{} nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6949 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6950
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6951 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6952 ;; @r{Return a copy lacking all elements.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6953 (nthcdr 5 '(pine fir oak maple))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6954 @result{} nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6955 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6956 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6957
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6958 @node nth, setcar, nthcdr, car cdr & cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6959 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6960 @section @code{nth}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6961 @findex nth
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 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
6964 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
6965 @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
6966
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6967 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6968 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
6969 @code{nth} would be:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6970
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6971 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6972 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6973 (defun nth (n list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6974 "Returns the Nth element of LIST.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6975 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
6976 (car (nthcdr n list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6977 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6978 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6979
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6980 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6981 (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
6982 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
6983
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6984 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
6985 This can be very convenient.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6986
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6987 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
6988 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
6989 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
6990 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
6991 is `one-based'.
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6994 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6995
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6996 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6997 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6998 (nth 0 '("one" "two" "three"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
6999 @result{} "one"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7001 (nth 1 '("one" "two" "three"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7002 @result{} "two"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7003 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7004 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7005
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7006 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
7007 @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
7008 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
7009 @code{setcdr} functions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7010
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7011 @node setcar, setcdr, nth, car cdr & cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7012 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7013 @section @code{setcar}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7014 @findex setcar
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7015
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7016 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
7017 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
7018 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
7019 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
7020 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
7021
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7022 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7023 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
7024 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
7025
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7026 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7027 (setq animals '(antelope giraffe lion tiger))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7028 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7029
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7030 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7031 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
7032 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
7033 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
7034 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
7035 built into the computing environment.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7036
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7037 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7038 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
7039 the list @code{(antelope giraffe lion tiger)}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7040
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7041 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7042 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7043 animals
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7044 @result{} (antelope giraffe lion tiger)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7045 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7046 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7047
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7048 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7049 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
7050 @code{(antelope giraffe lion tiger)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7051
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7052 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
7053 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
7054 @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
7055 @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
7056 usual fashion:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7057
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7058 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7059 (setcar animals 'hippopotamus)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7060 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7061
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7062 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7063 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7064 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
7065 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
7066
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7067 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7068 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7069 animals
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7070 @result{} (hippopotamus giraffe lion tiger)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7071 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7072 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7075 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
7076 @code{hippopotamus}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7077
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7078 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
7079 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
7080 @code{hippopotamus}; it @emph{changed} the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7081
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7082 @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
7083 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7084 @section @code{setcdr}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7085 @findex setcdr
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 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
7088 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
7089 a list rather than the first element.
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 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
7093 domesticated animals by evaluating the following expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7094
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7095 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7096 (setq domesticated-animals '(horse cow sheep goat))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7097 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7098
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7099 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7100 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7101 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
7102 @code{(horse cow sheep goat)}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7103
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7104 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7105 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7106 domesticated-animals
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7107 @result{} (horse cow sheep goat)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7108 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7109 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7110
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7111 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7112 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
7113 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
7114 @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
7115
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7116 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7117 (setcdr domesticated-animals '(cat dog))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7118 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7119
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7120 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7121 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
7122 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
7123 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
7124 evaluating the variable @code{domesticated-animals}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7125
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7126 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7127 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7128 domesticated-animals
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7129 @result{} (horse cat dog)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7130 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7131 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7134 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
7135 @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
7136 @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
7137
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7138 @node cons Exercise, , setcdr, car cdr & cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7139 @section Exercise
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7140
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7141 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
7142 @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
7143 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
7144 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
7145 @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
7146 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7147 @chapter Cutting and Storing Text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7148 @cindex Cutting and storing text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7149 @cindex Storing and cutting text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7150 @cindex Killing text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7151 @cindex Clipping text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7152 @cindex Erasing text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7153 @cindex Deleting text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7154
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7155 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
7156 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
7157 `yank' command.
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 (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
7160 @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
7161 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
7162 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
7163 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
7164 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
7165 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
7166
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7167 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7168 * 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
7169 * 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
7170 * 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
7171 * 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
7172 * 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
7173 * 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
7174 * cons & search-fwd Review::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7175 * search Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7176 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7177
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7178 @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
7179 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7180 @unnumberedsec Storing Text in a List
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7181 @end ifnottex
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 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
7184 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
7185 look like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7186
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7187 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7188 ("a piece of text" "previous piece")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7189 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7190
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7191 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7192 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7193 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
7194 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7195
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7196 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7197 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7198 (cons "another piece"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7199 '("a piece of text" "previous piece"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7200 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7201 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7202
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7203 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7204 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7205 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
7206 the echo area:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7207
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7208 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7209 ("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
7210 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7211
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7212 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
7213 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
7214 @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
7215 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
7216 second element of the original list:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7217
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7218 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7219 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7220 (car (nthcdr 1 '("another piece"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7221 "a piece of text"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7222 "previous piece")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7223 @result{} "a piece of text"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7224 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7225 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7226
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7227 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
7228 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
7229 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
7230 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
7231 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
7232 than nothing at all.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7233
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7234 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
7235 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
7236 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
7237 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
7238 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
7239 climb the foothills.
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 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
7242 retrieved. @xref{Yanking, , Yanking Text Back}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7243
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7244 @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
7245 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7246 @section @code{zap-to-char}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7247 @findex zap-to-char
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{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
7250 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
7251 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
7252 on the way to version 21.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7253
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7254 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
7255 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
7256
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7257 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
7258 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
7259 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
7260
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7261 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
7262
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7263 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7264 * Complete zap-to-char:: The complete implementation.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7265 * 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
7266 * zap-to-char body:: A short overview.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7267 * 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
7268 * progn:: The @code{progn} special form.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7269 * 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
7270 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7271
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7272 @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
7273 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7274 @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
7275 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7276
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7277 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
7278 @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
7279 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
7280 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
7281 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
7282 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
7283 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
7284 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
7285 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
7286 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
7287 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
7288 the @samp{s} in @samp{cursor}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7289
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7290 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
7291 ``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
7292 any text.
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 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
7295 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
7296 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
7297 deletion command.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7298
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7299 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7300 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
7301
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7302 @c v 19
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7303 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7304 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7305 (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
7306 "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
7307 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
7308 (interactive "*p\ncZap to char: ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7309 (kill-region (point)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7310 (progn
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7311 (search-forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7312 (char-to-string char) nil nil arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7313 (point))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7314 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7315 @end smallexample
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 @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
7318 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7319 @subsection The @code{interactive} Expression
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7322 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
7323 this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7324
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7325 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7326 (interactive "*p\ncZap to char: ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7327 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7328
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7329 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
7330 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
7331 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
7332 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
7333 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
7334 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
7335
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7336 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
7337 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
7338 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
7339 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
7340 cases, you see an error message.
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 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
7343 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
7344 @code{interactive}. According to the documentation for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7345 @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
7346 @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
7347 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
7348 It is a bug that it does.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7349
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7350 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
7351 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
7352 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
7353 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
7354 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
7355
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7356 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
7357 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
7358
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7359 Let us continue with the interactive specification.
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 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
7362 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
7363 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
7364 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
7365 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
7366 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
7367 this argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7368
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7369 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
7370 }. 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
7371 @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
7372 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
7373 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
7374
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7375 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
7376 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
7377
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7378 @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
7379 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7380 @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
7381
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7382 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
7383 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
7384 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
7385 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
7386
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7387 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7388 (kill-region (point) @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7389 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7390
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7391 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7392 @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
7393
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7394 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
7395 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
7396 @code{point}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7397
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7398 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
7399 @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
7400 then at @code{progn}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7401
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7402 @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
7403 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7404 @subsection The @code{search-forward} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7405 @findex search-forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7406
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7407 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
7408 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
7409 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
7410 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
7411 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
7412 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
7413 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
7414 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
7415
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7416 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7417 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
7418
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7419 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7420 (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
7421 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7422
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7423 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
7424
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7425 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7426 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7427 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
7428 string, such as @samp{"z"}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7429
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7430 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
7431 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
7432 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
7433 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
7434 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
7435 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
7436 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
7437 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
7438 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
7439 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
7440 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
7441 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
7442
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7443 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7444 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
7445 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
7446 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
7447
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7448 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7449 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
7450 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
7451 @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
7452 signal an error when the search fails.
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 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7455 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
7456 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
7457 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
7458 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
7459 backwards.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7460 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7461
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7462 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7463 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
7464
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7465 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7466 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7467 (search-forward "@var{target-string}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7468 @var{limit-of-search}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7469 @var{what-to-do-if-search-fails}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7470 @var{repeat-count})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7471 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7472 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7473
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7474 We will look at @code{progn} next.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7475
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7476 @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
7477 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7478 @subsection The @code{progn} Special Form
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7479 @findex progn
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 @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
7482 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
7483 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
7484 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
7485
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7486 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7487 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
7488
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7489 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7490 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7491 (progn
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7492 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7493 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7494 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7495
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7496 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
7497 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
7498 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
7499
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7500 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
7501 @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
7502 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
7503 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
7504 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
7505 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
7506
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7507 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
7508 @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
7509 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
7510 @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
7511 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
7512 second argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7513
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7514 @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
7515 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7516 @subsection Summing up @code{zap-to-char}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7517
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7518 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
7519 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
7520
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7521 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
7522 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
7523 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
7524 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
7525 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
7526 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
7527 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
7528
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7529 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
7530 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
7531 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
7532 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
7533 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
7534 needs for its second argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7535
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7536 @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
7537 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7538 @section @code{kill-region}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7539 @findex kill-region
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 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
7542 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
7543 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
7544
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7545 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
7546 @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
7547 @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
7548
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7549 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
7550 @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
7551 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
7552 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
7553 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
7554
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7555 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7556 * Complete kill-region:: The function definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7557 * condition-case:: Dealing with a problem.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7558 * delete-and-extract-region:: Doing the work.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7559 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7560
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7561 @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
7562 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7563 @unnumberedsubsec The Complete @code{kill-region} Definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7564 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7565
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7566 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7567 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
7568 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
7569 comments added:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7570
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7571 @c v 21
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7572 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7573 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7574 (defun kill-region (beg end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7575 "Kill between point and mark.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7576 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
7577 (interactive "r")
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 ;; 1. `condition-case' takes three arguments.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7582 ;; 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
7583 ;; information about the error signal is not
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7584 ;; stored for use by another function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7585 (condition-case nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7586 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7587
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7588 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7589 ;; 2. The second argument to `condition-case'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7590 ;; 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
7591 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7592
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7593 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7594 ;; 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
7595 ;; 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
7596 ;; 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
7597 (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
7598 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7599
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7600 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7601 ;; `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
7602 ;; 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
7603 ;; previous command.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7604 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7605 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7606 ;; `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
7607 ;; `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
7608 (when string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7609 (if (eq last-command 'kill-region)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7610 ;; if true, prepend string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7611 (kill-append string (< end beg))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7612 (kill-new string)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7613 (setq this-command 'kill-region))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7614 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7615
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7616 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7617 ;; 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
7618 ;; what to do with an error.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7619 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7620 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7621 ;; 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
7622 ;; 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
7623 ;; if text or buffer is read-only)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7624 ;; then the body is executed.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7625 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7626 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7627 ((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
7628 ;; then...
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7629 (copy-region-as-kill beg end)
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7632 (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
7633 (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
7634 ;; 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
7635 (barf-if-buffer-read-only)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7636 ;; 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
7637 (signal 'text-read-only (list (current-buffer)))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7638 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7639 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7640
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7641 @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
7642 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7643 @subsection @code{condition-case}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7644 @findex condition-case
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7645
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7646 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
7647 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
7648 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
7649 ``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
7650 shows you a message.
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 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
7653 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
7654 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
7655 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
7656 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
7657 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
7658 special form.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7659
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7660 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7661 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
7662
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7663 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7664 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7665 (condition-case
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7666 @var{var}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7667 @var{bodyform}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7668 @var{error-handler}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7669 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7670 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7671
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7672 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
7673 @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
7674 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
7675 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
7676
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7677 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
7678 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
7679 correctly.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7680
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7681 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
7682 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
7683 names.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7684
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7685 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
7686 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
7687 @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
7688 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
7689 part of the error handler is run.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7690
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7691 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
7692 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
7693
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7694 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
7695 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
7696 handler is run.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7697
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7698 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
7699 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
7700 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
7701 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
7702 discarded.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7703
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7704 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7705 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
7706 @code{condition-case} works like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7707
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7708 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7709 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7710 @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
7711 @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
7712 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7713 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7714
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7715 @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
7716 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7717 @subsection @code{delete-and-extract-region}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7718 @findex delete-and-extract-region
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7719
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7720 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
7721 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
7722 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
7723 error.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7724
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7725 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
7726 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
7727 The code looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7728
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7729 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7730 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7731 (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
7732 (when string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7733 (if (eq last-command 'kill-region)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7734 (kill-append string (< end beg))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7735 (kill-new string)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7736 (setq this-command 'kill-region))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7737 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7738 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7739
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7740 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
7741 @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
7742 @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
7743 @code{last-command} and @code{this-command}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7744
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7745 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
7746 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
7747 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
7748 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
7749 error.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7750
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7751 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
7752 @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
7753 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
7754 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
7755 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
7756 is simply a shorthand.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7757
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7758 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
7759 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
7760 text was removed.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7761
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7762 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
7763 @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
7764 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
7765 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
7766 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
7767 That is what the Lisp interpreter does.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7768
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7769 @cindex Macro, lisp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7770 @cindex Lisp macro
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7771 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
7772 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
7773 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
7774 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
7775 `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
7776 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
7777 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
7778 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
7779 @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
7780 Digressing into C}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7781
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7782 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7783 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
7784 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
7785
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7786 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7787 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7788 (if (eq last-command 'kill-region)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7789 (kill-append string (< end beg))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7790 (kill-new string)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7791 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7792 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7793
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7794 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
7795 @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
7796
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7797 @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
7798 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
7799 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
7800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7801 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7802 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
7803 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
7804
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7805 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7806 (kill-append string (< end beg))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7807 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7808
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7809 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7810 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
7811 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
7812 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
7813 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
7814 @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
7815
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7816 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
7817 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
7818 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
7819 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
7820 order is correct.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7821
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7822 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
7823 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
7824 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
7825 @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
7826
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7827 @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
7828 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7829 @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
7830 @findex delete-and-extract-region
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7831 @cindex C, a digression into
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7832 @cindex Digression into C
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{zap-to-char} command uses the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7835 @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
7836 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
7837 @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
7838 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
7839 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
7840 @code{copy-region-as-kill}}.)
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 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
7843 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
7844
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7845 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
7846 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
7847 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
7848 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
7849
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7850 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7851 Like many of the other Emacs primitives,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7852 @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
7853 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
7854 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7855
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7856 @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
7857 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7858 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7859 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
7860 Sdelete_and_extract_region, 2, 2, 0,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7861 "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
7862 (start, end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7863 Lisp_Object start, end;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7864 @{
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7865 validate_region (&start, &end);
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7866 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
7867 @}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7868 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7869 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7870
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7871 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
7872 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
7873 @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
7874 @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
7875 parts inside of parentheses:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7876
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7877 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7878 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7879 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
7880 @code{delete-and-extract-region}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7881
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7882 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7883 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
7884 @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
7885 @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
7886 instead.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7887
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7888 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7889 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
7890 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
7891 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
7892
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7893 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7894 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
7895 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
7896 arguments.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7897
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7898 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7899 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
7900 @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
7901 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
7902 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
7903 (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
7904
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7905 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
7906 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
7907 @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
7908 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
7909 and provides a prompt.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7910
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7911 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7912 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
7913 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
7914 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
7915 return.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7916
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7917 @need 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7918 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
7919 written like this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7922 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7923 "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
7924 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
7925 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7926 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7927 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7928
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7929 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7930 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
7931 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
7932 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
7933 consists of the following two lines:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7934
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7935 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7936 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7937 validate_region (&start, &end);
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7938 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
7939 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7940 @end smallexample
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 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
7943 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
7944 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
7945 deletes the text.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7946
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7947 @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
7948 updates the buffer and does other things.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7949
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7950 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
7951 @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
7952 (end)}}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7953
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7954 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
7955 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
7956 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
7957 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
7958 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
7959
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7960 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
7961 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
7962 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
7963 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
7964 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
7965
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7966 @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
7967 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
7968
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7969 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7970 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
7971
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7972 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7973 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
7974 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7977 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
7978 and the ending position, @code{end}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7979
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7980 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
7981 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
7982 all work.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7983
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7984 @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
7985 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7986 @section Initializing a Variable with @code{defvar}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7987 @findex defvar
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7988 @cindex Initializing a variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
7989 @cindex Variable initialization
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 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
7992 @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
7993 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
7994 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
7995 @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
7996 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
7997 form.
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 (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
8000 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
8001 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
8002
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8003 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
8004 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
8005 name comes from ``define variable''.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8006
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8007 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
8008 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
8009 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
8010 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
8011 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
8012 documentation string.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8013
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8014 (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
8015 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
8016 (@xref{defcustom, , Setting Variables with @code{defcustom}}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8017
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8018 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8019 * See variable current value::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8020 * defvar and asterisk:: An old-time convention.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8021 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8022
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8023 @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
8024 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8025 @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
8026 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8027
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8028 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
8029 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
8030 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
8031 (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
8032 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
8033 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
8034 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
8035 @code{kill-ring}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8036
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8037 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8038 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8039 Documentation:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8040 List of killed text sequences.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8041 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
8042 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
8043 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8044 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8045 interact nicely with `interprogram-cut-function' and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8046 `interprogram-paste-function'. The functions `kill-new',
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8047 `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
8048 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
8049 ring directly.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8050 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8051 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8052
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8053 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8054 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
8055
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8056 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8057 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8058 (defvar kill-ring nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8059 "List of killed text sequences.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8060 @dots{}")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8061 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8062 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8063
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8064 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8065 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
8066 @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
8067 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
8068 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
8069 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
8070 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
8071 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
8072 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
8073 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
8074
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8075 @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
8076 @subsection @code{defvar} and an asterisk
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8077 @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
8078 @findex defvar @r{with an asterisk}
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 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
8081 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
8082 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
8083 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
8084 @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
8085 the Customization commands. (@xref{defcustom, , Setting Variables
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8086 with @code{defcustom}}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8087
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8088 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
8089 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
8090 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
8091 string. For example:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8094 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8095 (defvar shell-command-default-error-buffer nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8096 "*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
8097 @dots{} ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8098 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8099 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8100
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8101 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8102 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
8103 command to change the value of
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8104 @code{shell-command-default-error-buffer} temporarily.
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 @findex edit-options
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8107 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
8108 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
8109 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
8110 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
8111 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
8112 @xref{Emacs Initialization, , Your @file{.emacs} File}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8113
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8114 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
8115 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
8116 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
8117 Values, emacs, The GNU Emacs Manual}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8118
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8119 @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
8120 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8121 @section @code{copy-region-as-kill}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8122 @findex copy-region-as-kill
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8123 @findex nthcdr
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8124
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8125 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
8126 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
8127 in the @code{kill-ring}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8128
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8129 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
8130 @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
8131 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
8132 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
8133 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
8134 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
8135
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8136 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8137 * 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
8138 * 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
8139 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8140
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8141 @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
8142 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8143 @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
8144 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8145
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8146 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8147 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
8148 function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8149
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8150 @smallexample
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 (defun copy-region-as-kill (beg end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8153 "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
8154 In Transient Mark mode, deactivate the mark.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8155 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
8156 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
8157 (interactive "r")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8158 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8159 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8160 (if (eq last-command 'kill-region)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8161 (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
8162 (kill-new (buffer-substring beg end)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8163 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8164 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8165 (if transient-mark-mode
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8166 (setq deactivate-mark t))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8167 nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8168 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8169 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8170
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8171 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8172 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
8173
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8174 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8175 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8176 (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
8177 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8178 (interactive "r")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8179 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8180 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8181 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8182
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8183 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
8184 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
8185 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
8186 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
8187 almost becoming routine.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8188
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8189 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
8190 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
8191 `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
8192 certain side-effects.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8193
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8194 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
8195 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
8196 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
8197 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
8198 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
8199 highlighted.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8201 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
8202 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
8203 @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
8204 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
8205 ring.
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 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
8208 @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
8209 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
8210 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
8211 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
8212 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
8213 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
8214
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8215 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
8216 if Transient Mark mode is turned on.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8217
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8218 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
8219
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8220 @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
8221 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8222 @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
8223
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8224 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
8225 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
8226 ,@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
8227 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
8228 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
8229 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
8230 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
8231 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
8232 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
8233
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8234 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
8235 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
8236 previous Emacs command.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8237
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8238 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8239 * last-command & this-command::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8240 * kill-append function::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8241 * kill-new function::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8242 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8243
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8244 @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
8245 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8246 @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
8247 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8248
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8249 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
8250 @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
8251 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
8252 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
8253 @code{this-command}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8254
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8255 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
8256 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
8257 @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
8258 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
8259 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
8260 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
8261 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
8262 @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
8263 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
8264 function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8265
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8266 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8267 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
8268 a function we have not yet seen:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8269
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8270 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8271 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8272 (if (eq last-command 'kill-region)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8273 ;; @r{then-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8274 (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
8275 ;; @r{else-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8276 (kill-new (buffer-substring beg end)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8277 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8278 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8279
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8280 @findex eq @r{(example of use)}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8281 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8282 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
8283 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
8284 @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
8285 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
8286 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
8287 @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
8288 expressions are the same.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8289
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8290 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
8291 interpreter calls the @code{kill-append} function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8292
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8293 @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
8294 @unnumberedsubsubsec The @code{kill-append} function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8295 @findex kill-append
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8296
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8297 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8298 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
8299
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8300 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8301 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8302 (defun kill-append (string before-p)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8303 "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
8304 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
8305 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
8306 it."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8307 (kill-new (if before-p
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8308 (concat string (car kill-ring))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8309 (concat (car kill-ring) string))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8310 t))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8311 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8312 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8313
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8314 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8315 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
8316 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
8317 a moment.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8318
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8319 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
8320 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
8321 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
8322 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
8323
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8324 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8325 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8326 (if before-p ; @r{if-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8327 (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
8328 (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
8329 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8330 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8331
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8332 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8333 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
8334 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
8335 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
8336 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
8337 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
8338 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
8339 previously saved text.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8340
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8341 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
8342 @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
8343 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
8344 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
8345 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
8346 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
8347 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
8348 @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
8349 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
8350 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
8351 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
8352 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
8353 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
8354 @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
8355
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8356 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8357 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
8358 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
8359
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8360 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8361 (concat string (car kill-ring))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8362 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8363
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8364 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8365 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8366 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
8367 after the old text:
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 (concat (car kill-ring) string))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8371 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8372
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8373 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
8374 @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
8375 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
8376
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8377 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8378 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8379 (concat "abc" "def")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8380 @result{} "abcdef"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8381 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8382
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8383 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8384 (concat "new "
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8385 (car '("first element" "second element")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8386 @result{} "new first element"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8387
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8388 (concat (car
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8389 '("first element" "second element")) " modified")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8390 @result{} "first element modified"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8391 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8392 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8393
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8394 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
8395 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
8396 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
8397 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
8398
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8399 @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
8400 @unnumberedsubsubsec The @code{kill-new} function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8401 @findex kill-new
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8402
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8403 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8404 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
8405
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8406 @smallexample
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 (defun kill-new (string &optional replace)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8409 "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
8410 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
8411 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
8412 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
8413 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
8414 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8415 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8416 (and (fboundp 'menu-bar-update-yank-menu)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8417 (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
8418 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8419 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8420 (if (and replace kill-ring)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8421 (setcar kill-ring string)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8422 (setq kill-ring (cons string kill-ring))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8423 (if (> (length kill-ring) kill-ring-max)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8424 (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
8425 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8426 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8427 (setq kill-ring-yank-pointer kill-ring)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8428 (if interprogram-cut-function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8429 (funcall interprogram-cut-function string (not replace))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8430 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8431 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8432
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8433 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
8434
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8435 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8436 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
8437
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8438 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8439 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
8440 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8441
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8442 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8443 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
8444
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8445 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
8446 @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
8447
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8448 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8449 The critical lines are these:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8450
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8451 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8452 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8453 (if (and replace kill-ring)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8454 ;; @r{then}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8455 (setcar kill-ring string)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8456 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8457 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8458 ;; @r{else}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8459 (setq kill-ring (cons string kill-ring))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8460 (if (> (length kill-ring) kill-ring-max)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8461 ;; @r{avoid overly long kill ring}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8462 (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
8463 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8464 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8465 (setq kill-ring-yank-pointer kill-ring)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8466 (if interprogram-cut-function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8467 (funcall interprogram-cut-function string (not replace))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8468 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8469 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8470
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8471 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
8472 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
8473 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
8474
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8475 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8476 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
8477 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
8478 expression is executed:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8481 (setcar kill-ring string)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8482 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8483
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8484 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
8485 @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
8486 first element.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8487
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8488 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
8489 else-part of the condition is executed:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8492 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8493 (setq kill-ring (cons string kill-ring))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8494 (if (> (length kill-ring) kill-ring-max)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8495 (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
8496 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8497 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8500 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
8501 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
8502 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
8503 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
8504
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8505 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
8506
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8507 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
8508 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
8509 ring.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8510
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8511 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8512 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
8513
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8514 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8515 (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
8516 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8517
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8518 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8519 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8520 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
8521 @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
8522
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8523 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8524 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8525 example-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8526 @result{} ("here is a clause" "another clause")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8527 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8528 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8529
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8530 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8531 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8532 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
8533 following expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8534 @findex cons, @r{example}
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 (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
8538 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8539
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8540 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8541 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8542 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
8543
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8544 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8545 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8546 example-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8547 @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
8548 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8549 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8550
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8551 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8552 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
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 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
8556 the function. Here is the line again:
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 (setq kill-ring (cons string kill-ring))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8560 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8561
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8562 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8563 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
8564 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
8565
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8566 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8567 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8568 (if (> (length kill-ring) kill-ring-max)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8569 (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
8570 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8571 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8572
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8573 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
8574 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
8575 @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
8576 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
8577 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
8578 @code{nthcdr} and @code{setcdr}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8579
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8580 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
8581 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
8582 @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
8583 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
8584 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
8585 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
8586 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
8587 the last element of the kill ring.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8588
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8589 @findex nthcdr, @r{example}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8590 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
8591 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
8592 @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
8593
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8594 @findex setcdr, @r{example}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8595 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
8596 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
8597 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
8598
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8599 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
8600 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
8601 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
8602 find the value of @code{trees}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8603
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8604 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8605 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8606 (setq trees '(maple oak pine birch))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8607 @result{} (maple oak pine birch)
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
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8610 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8611 (setcdr (nthcdr 2 trees) nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8612 @result{} nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8613
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8614 trees
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8615 @result{} (maple oak pine)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8616 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8617 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8618
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8619 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8620 (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
8621 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
8622
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8623 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
8624 @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
8625 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
8626 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
8627 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
8628
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8629 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8630 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
8631
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8632 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8633 (setq kill-ring-yank-pointer kill-ring)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8634 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8635
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8636 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
8637 the @code{kill-ring}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8638
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8639 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
8640 @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
8641 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
8642 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
8643 @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
8644
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8645 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8646 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
8647
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8648 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8649 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8650 (and (fboundp 'menu-bar-update-yank-menu)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8651 (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
8652 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8653 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8654
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8655 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8656 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
8657
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8658 @findex and, @r{introduced}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8659 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
8660 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
8661 @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
8662 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
8663 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
8664 @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
8665 @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
8666 are true.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8667 @findex and
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 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
8670 @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
8671 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
8672 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
8673 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
8674 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
8675 Errors, , Generate an Error Message}).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8676
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8677 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8678 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
8679 this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8680
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8681 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8682 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8683 if @var{the-menu-bar-function-exists}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8684 then @var{execute-it}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8685 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8686 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8687
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8688 @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
8689 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
8690 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
8691 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
8692
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8693 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
8694 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
8695 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
8696 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
8697 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
8698 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
8699
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8700 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8701 The expression looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8702
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8703 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8704 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8705 (if interprogram-cut-function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8706 (funcall interprogram-cut-function string (not replace))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8707 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8708 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8709
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8710 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
8711 @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
8712 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
8713 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
8714 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
8715
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8716 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
8717 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
8718 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
8719
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8720 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
8721 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
8722 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
8723 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
8724 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
8725 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
8726
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8727 @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
8728 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8729 @section Review
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 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
8732
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8733 @table @code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8734 @item car
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8735 @itemx cdr
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8736 @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
8737 second and subsequent elements of a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8738
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8739 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8740 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8741
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8742 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8743 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8744 (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
8745 @result{} 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8746 (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
8747 @result{} (2 3 4 5 6 7)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8748 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8749 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8750
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8751 @item cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8752 @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
8753 second argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8754
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8755 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8756 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8757
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8758 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8759 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8760 (cons 1 '(2 3 4))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8761 @result{} (1 2 3 4)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8762 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8763 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8764
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8765 @item nthcdr
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8766 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
8767 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8768 The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8769 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8770 $n^{th}$
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8771 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8772 @code{cdr}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8773 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8774 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
8775
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8776 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8777 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8778
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8779 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8780 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8781 (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
8782 @result{} (4 5 6 7)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8783 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8784 @end smallexample
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 @item setcar
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8787 @itemx setcdr
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8788 @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
8789 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
8790
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8791 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8792 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8793
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8794 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8795 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8796 (setq triple '(1 2 3))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8797
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8798 (setcar triple '37)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8799
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8800 triple
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8801 @result{} (37 2 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8802
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8803 (setcdr triple '("foo" "bar"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8804
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8805 triple
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8806 @result{} (37 "foo" "bar")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8807 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8808 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8809
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8810 @item progn
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8811 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
8812 last.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8813
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8814 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8815 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8816
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8817 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8818 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8819 (progn 1 2 3 4)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8820 @result{} 4
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8821 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8822 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8823
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8824 @item save-restriction
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8825 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
8826 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
8827
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8828 @item search-forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8829 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
8830
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8831 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8832 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8833 Takes four arguments:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8834
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8835 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8836 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8837 The string to search for.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8838
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8839 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8840 Optionally, the limit of the search.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8841
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8842 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8843 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
8844 error message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8845
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8846 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8847 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
8848 search goes backwards.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8849 @end enumerate
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 @item kill-region
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8852 @itemx delete-region
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8853 @itemx copy-region-as-kill
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8854
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8855 @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
8856 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
8857 by yanking.
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 @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
8860 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
8861
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8862 @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
8863 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
8864 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
8865 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8866
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8867 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8868 @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
8869 @section Searching Exercises
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8870
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8871 @itemize @bullet
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 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
8874 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
8875 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
8876 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
8877 @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
8878 @code{test-search} instead.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8879
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8880 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8881 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
8882 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
8883 print an appropriate message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8884 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8885
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8886 @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
8887 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8888 @chapter How Lists are Implemented
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8889 @cindex Lists in a computer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8890
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8891 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
8892 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
8893 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
8894 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
8895 @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
8896 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
8897 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
8898 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
8899 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
8900 @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
8901
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8902 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
8903 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
8904
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8905 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8906 * Lists diagrammed::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8907 * Symbols as Chest:: Exploring a powerful metaphor.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8908 * List Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8909 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8910
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8911 @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
8912 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8913 @unnumberedsec Lists diagrammed
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8914 @end ifnottex
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 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
8917 @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
8918 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
8919 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
8920 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
8921 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
8922 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
8923
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8924 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8925 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
8926
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8927 @c clear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8928 @c !!! cons-cell-diagram #1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8929 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8930 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8931 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8932 ___ ___ ___ ___ ___ ___
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8933 |___|___|--> |___|___|--> |___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8934 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8935 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8936 --> rose --> violet --> buttercup
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8937 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8938 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8939 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8940 @ifset print-postscript-figures
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 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8943 @image{cons-1}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8944 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8945 % \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
8946 % \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
8947 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8948 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8949 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8950 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8951 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8952 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8953 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8954 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8955 ___ ___ ___ ___ ___ ___
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8956 |___|___|--> |___|___|--> |___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8957 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8958 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8959 --> rose --> violet --> buttercup
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8960 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8961 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8962 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8963 @end ifclear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8964
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8965 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8966 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
8967 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
8968 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
8969 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
8970 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
8971 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
8972 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
8973 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
8974 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
8975
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8976 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8977 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
8978 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
8979 evaluation of the expression
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8982 (setq bouquet '(rose violet buttercup))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8983 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8984
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8985 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8986 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8987 creates a situation like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8988
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8989 @c cons-cell-diagram #2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8990 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8991 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8992 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8993 bouquet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8994 |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8995 | ___ ___ ___ ___ ___ ___
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8996 --> |___|___|--> |___|___|--> |___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8997 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8998 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
8999 --> rose --> violet --> buttercup
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9000 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9001 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9002 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9003 @ifset print-postscript-figures
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 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9006 @image{cons-2}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9007 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9008 % \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
9009 % \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
9010 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9011 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9012 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9013 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9014 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9015 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9016 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9017 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9018 bouquet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9019 |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9020 | ___ ___ ___ ___ ___ ___
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9021 --> |___|___|--> |___|___|--> |___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9022 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9023 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9024 --> rose --> violet --> buttercup
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9025 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9026 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9027 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9028 @end ifclear
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9031 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
9032 pair of boxes.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9033
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9034 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9035 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
9036 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9037
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9038 @c cons-cell-diagram #2a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9039 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9040 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9041 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9042 bouquet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9043 |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9044 | -------------- --------------- ----------------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9045 | | car | cdr | | car | cdr | | car | cdr |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9046 -->| rose | o------->| violet | o------->| butter- | nil |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9047 | | | | | | | cup | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9048 -------------- --------------- ----------------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9049 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9050 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9051 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9052 @ifset print-postscript-figures
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 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9055 @image{cons-2a}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9056 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9057 % \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
9058 % \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
9059 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9060 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9061 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9062 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9063 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9064 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9065 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9066 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9067 bouquet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9068 |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9069 | -------------- --------------- ----------------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9070 | | car | cdr | | car | cdr | | car | cdr |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9071 -->| rose | o------->| violet | o------->| butter- | nil |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9072 | | | | | | | cup | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9073 -------------- --------------- ----------------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9074 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9075 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9076 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9077 @end ifclear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9078
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9079 (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
9080 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
9081 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
9082 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
9083 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
9084 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
9085 @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
9086 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
9087 address-boxes for the list.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9088
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9089 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
9090 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
9091 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
9092 evaluation of the following expression
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9095 (setq flowers (cdr bouquet))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9096 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9097
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9098 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9099 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9100 produces this:
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 @c cons-cell-diagram #3
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9103 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9104 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9105 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9106 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9107 bouquet flowers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9108 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9109 | ___ ___ | ___ ___ ___ ___
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9110 --> | | | --> | | | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9111 |___|___|----> |___|___|--> |___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9112 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9113 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9114 --> rose --> violet --> buttercup
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9115 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9116 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9117 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9118 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9119 @ifset print-postscript-figures
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 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9122 @image{cons-3}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9123 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9124 % \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
9125 % \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
9126 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9127 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9128 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9129 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9130 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9131 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9132 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9133 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9134 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9135 bouquet flowers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9136 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9137 | ___ ___ | ___ ___ ___ ___
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9138 --> | | | --> | | | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9139 |___|___|----> |___|___|--> |___|___|--> nil
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 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9142 --> rose --> violet --> buttercup
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9143 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9144 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9145 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9146 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9147 @end ifclear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9148
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9149 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9150 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
9151 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
9152 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
9153 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
9154
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9155 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
9156 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
9157 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
9158 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
9159 information about cons cells and dotted pairs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9160
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9161 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9162 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
9163 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
9164 the expression
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9167 (setq bouquet (cons 'lily bouquet))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9168 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9169
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9170 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9171 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9172 produces:
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 @c cons-cell-diagram #4
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9175 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9176 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9177 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9178 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9179 bouquet flowers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9180 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9181 | ___ ___ ___ ___ | ___ ___ ___ ___
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9182 --> | | | | | | --> | | | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9183 |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9184 | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9185 | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9186 --> lily --> rose --> violet --> buttercup
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9187 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9188 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9189 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9190 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9191 @ifset print-postscript-figures
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 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9194 @image{cons-4}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9195 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9196 % \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
9197 % \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
9198 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9199 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9200 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9201 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9202 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9203 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9204 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9205 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9206 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9207 bouquet flowers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9208 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9209 | ___ ___ ___ ___ | ___ ___ ___ ___
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9210 --> | | | | | | --> | | | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9211 |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil
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 | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9214 --> lily --> rose --> violet --> buttercup
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9215 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9216 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9217 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9218 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9219 @end ifclear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9220
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9221 @need 1200
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 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
9224 @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
9225
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9226 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9227 (eq (cdr (cdr bouquet)) flowers)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9228 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9231 which returns @code{t} for true.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9232
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9233 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
9234 @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
9235 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
9236 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
9237
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9238 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
9239 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
9240 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
9241 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
9242 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
9243 brilliantly simple!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9244
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9245 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
9246 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
9247
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9248 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
9249 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
9250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9251 @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
9252 @section Symbols as a Chest of Drawers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9253 @cindex Symbols as a Chest of Drawers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9254 @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
9255 @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
9256
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9257 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
9258 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
9259 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
9260 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
9261 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
9262
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9263 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
9264 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
9265 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
9266 where the buried treasure lies.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9267
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9268 (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
9269 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
9270 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
9271 @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
9272 Reference Manual}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9273
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9274 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9275 Here is a fanciful representation:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9276
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9277 @c chest-of-drawers diagram
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9278 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9279 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9280 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9281 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9282 Chest of Drawers Contents of Drawers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9283
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9284 __ o0O0o __
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 | symbol name | bouquet
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 | symbol definition | [none]
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 | directions to | [map to]
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9296 | variable value | (rose violet buttercup)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9297 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9298 +---------------------+
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9299 | directions to |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9300 | property list | [not described here]
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9301 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9302 +---------------------+
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9303 |/ \|
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9304 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9305 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9306 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9307 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9308 @ifset print-postscript-figures
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 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9311 @image{drawers}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9312 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9313 % \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
9314 % \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
9315 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9316 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9317 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9318 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9319 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9320 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9321 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9322 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9323 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9324 Chest of Drawers Contents of Drawers
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9325
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9326 __ o0O0o __
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 | symbol name | bouquet
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 | symbol definition | [none]
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 | directions to | [map to]
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9338 | variable value | (rose violet buttercup)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9339 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9340 +---------------------+
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9341 | directions to |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9342 | property list | [not described here]
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 +---------------------+
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9345 |/ \|
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9346 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9347 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9348 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9349 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9350 @end ifclear
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 List Exercise, , Symbols as Chest, List Implementation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9353 @section Exercise
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9354
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9355 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
9356 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
9357 @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
9358 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
9359
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9360 @node Yanking, Loops & Recursion, List Implementation, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9361 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9362 @chapter Yanking Text Back
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9363 @findex yank
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9364 @findex rotate-yank-pointer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9365 @cindex Text retrieval
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9366 @cindex Retrieving text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9367 @cindex Pasting text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9368
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9369 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
9370 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
9371 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
9372 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
9373 the original buffer).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9374
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9375 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
9376 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
9377 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
9378 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
9379 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
9380 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
9381 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
9382 `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
9383 that holds the text is a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9384 @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
9385 list is handled as a ring.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9386
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9387 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9388 * 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
9389 * 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
9390 * yank nthcdr Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9391 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9392
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9393 @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
9394 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9395 @section Kill Ring Overview
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9396 @cindex Kill ring overview
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9397
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9398 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
9399
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9400 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9401 ("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
9402 @end smallexample
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 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
9405 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
9406 buffer where my cursor is located.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9407
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9408 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
9409 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
9410 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
9411
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9412 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
9413 @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
9414 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
9415 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
9416
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9417 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
9418 @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
9419 @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
9420
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9421 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9422 (insert (car kill-ring-yank-pointer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9423 @end smallexample
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 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
9426 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
9427 and the @code{rotate-yank-pointer} function.
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 @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
9430 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9431 @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
9432
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9433 @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
9434 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
9435 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
9436
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9437 @need 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9438 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
9439
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9440 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9441 ("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
9442 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9443
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9444 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9445 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9446 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
9447 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
9448
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9449 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9450 ("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
9451 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9452
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9453 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
9454 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
9455 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
9456 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
9457 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
9458 text. Here is a diagram:
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 @c cons-cell-diagram #5
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9461 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9462 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9463 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9464 kill-ring kill-ring-yank-pointer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9465 | |
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 ---> | | | --> | | | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9468 |___|___|----> |___|___|--> |___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9469 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9470 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9471 | | --> "yet more text"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9472 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9473 | --> "a different piece of text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9474 |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9475 --> "some text"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9476 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9477 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9478 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9479 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9480 @ifset print-postscript-figures
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 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9483 @image{cons-5}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9484 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9485 % \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
9486 % \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
9487 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9488 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9489 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9490 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9491 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9492 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9493 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9494 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9495 kill-ring kill-ring-yank-pointer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9496 | |
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 ---> | | | --> | | | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9499 |___|___|----> |___|___|--> |___|___|--> nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9500 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9501 | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9502 | | --> "yet more text"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9503 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9504 | --> "a different piece of text
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9505 |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9506 --> "some text"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9507 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9508 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9509 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9510 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9511 @end ifclear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9512
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9513 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
9514 @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
9515 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
9516 @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
9517 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
9518 spoken of as pointing to a list.
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 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
9521 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
9522 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
9523 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
9524 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
9525 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
9526 inserted.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9527
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9528 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
9529 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
9530 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
9531 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
9532 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
9533 @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
9534 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
9535 @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
9536 @xref{Kill Ring, , Handling the Kill Ring}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9537
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9538 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9539 @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
9540 @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
9541
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9542 @itemize @bullet
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 @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
9545 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
9546 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
9547 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
9548 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
9549 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
9550
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9551 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9552 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
9553 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
9554 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9555
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9556 @node Loops & Recursion, Regexp Search, Yanking, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9557 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9558 @chapter Loops and Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9559 @cindex Loops and recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9560 @cindex Recursion and loops
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9561 @cindex Repetition (loops)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9562
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9563 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
9564 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
9565 loop, and the other uses @dfn{recursion}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9566
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9567 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
9568 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
9569 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
9570 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
9571 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
9572 have on humans.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9573
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9574 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
9575 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
9576 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
9577 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
9578 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
9579 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
9580 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
9581 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
9582 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
9583 @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
9584 15 and 30 times their default value.}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9585
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9586 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9587 * 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
9588 * dolist dotimes::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9589 * Recursion:: Causing a function to call itself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9590 * Looping exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9591 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9592
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9593 @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
9594 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9595 @section @code{while}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9596 @cindex Loops
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9597 @findex while
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9598
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9599 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
9600 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
9601 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
9602 next, however, is different.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9603
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9604 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
9605 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
9606 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
9607 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
9608 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
9609 @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
9610 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
9611 body of the expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9612
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9613 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9614 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
9615
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9616 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9617 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9618 (while @var{true-or-false-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9619 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9620 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9621 @end smallexample
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 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9624 * 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
9625 * 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
9626 * 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
9627 * 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
9628 * 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
9629 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9630
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9631 @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
9632 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9633 @unnumberedsubsec Looping with @code{while}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9634 @end ifnottex
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 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
9637 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
9638 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
9639 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
9640 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
9641 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
9642 expression and `exits the loop'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9643
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9644 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
9645 @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
9646 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
9647 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
9648 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
9649 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
9650 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
9651 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
9652
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9653 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
9654 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
9655 @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
9656 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
9657 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
9658 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
9659 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
9660 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
9661 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
9662 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
9663 are repeatedly evaluated.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9664
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9665 @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
9666 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9667 @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
9668
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9669 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
9670 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
9671 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
9672 create a short example to illustrate it.
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 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
9675 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
9676 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
9677 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
9678 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
9679 @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
9680 @code{while} loop.
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 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9683 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
9684 evaluating the following @code{setq} expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9685
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9686 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9687 (setq empty-list ())
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9688 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9689
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9690 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9691 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
9692 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
9693 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
9694 echo area:
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 empty-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9698 @end smallexample
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 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
9701 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
9702 evaluating the following two expressions:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9705 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9706 (setq animals '(gazelle giraffe lion tiger))
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 animals
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9709 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9710 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9711
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9712 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
9713 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
9714 written like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9715
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9716 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9717 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9718 (while animals
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9719 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9720 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9721 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9722
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9723 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9724 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
9725 @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
9726 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
9727 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
9728 to be false.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9729
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9730 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
9731 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
9732 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
9733 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
9734 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
9735 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
9736 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
9737 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
9738
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9739 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
9740 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
9741 following expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9742
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9743 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9744 (setq animals (cdr animals))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9745 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9746
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9747 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9748 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
9749 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
9750 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
9751 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
9752 @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
9753
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9754 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
9755 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
9756 looks like this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9759 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9760 (while @var{test-whether-list-is-empty}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9761 @var{body}@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9762 @var{set-list-to-cdr-of-list})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9763 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9764 @end smallexample
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 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
9767 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
9768 own.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9769
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9770 @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
9771 @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
9772 @findex print-elements-of-list
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 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
9775 loop with a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9776
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9777 @cindex @file{*scratch*} buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9778 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
9779 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
9780 following expression inside of Info, as usual.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9781
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9782 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
9783 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
9784 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
9785 earlier versions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9786
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9787 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
9788 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
9789 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
9790 (@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
9791 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
9792
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9793 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
9794 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
9795 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
9796 @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
9797 @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
9798 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
9799 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
9800 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
9801 each @samp{^J} stands for a `newline'.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9802
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9803 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9804 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
9805 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
9806 results.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9807
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9808 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9809 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9810 (setq animals '(gazelle giraffe lion tiger))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9811
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9812 (defun print-elements-of-list (list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9813 "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
9814 (while list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9815 (print (car list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9816 (setq list (cdr list))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9817
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9818 (print-elements-of-list animals)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9819 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9820 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9821
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9822 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9823 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9824 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
9825 this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9828 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9829 giraffe
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9830
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9831 gazelle
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9832
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9833 lion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9834
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9835 tiger
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9836 nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9837 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9838 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9839
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9840 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
9841 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
9842 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
9843 @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
9844 @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
9845
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9846 @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
9847 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9848 @subsection A Loop with an Incrementing Counter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9849
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9850 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
9851 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
9852 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
9853 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
9854 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
9855 repeats itself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9856
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9857 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
9858 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
9859 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
9860 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
9861 @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
9862 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
9863 @code{1+} is a built-in function in Emacs Lisp that adds 1 to its
42506
d918430979ea Put @w{...} around an expression with a poor printed copy page break.
Robert J. Chassell <bob@rattlesnake.com>
parents: 42109
diff changeset
9864 argument. (The expression @w{@code{(1+ count)}} has the same result as
42562
fb149efd0c72 Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents: 42506
diff changeset
9865 @w{@code{(+ count 1)}}, but is easier for a human to read.)
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9866
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9867 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9868 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
9869 counter looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9870
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9871 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9872 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9873 @var{set-count-to-initial-value}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9874 (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
9875 @var{body}@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9876 (setq count (1+ count))) ; @r{incrementer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9877 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9878 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9879
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9880 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9881 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
9882 is set to 1.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9883
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9884 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9885 * Incrementing Example:: Counting pebbles in a triangle.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9886 * 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
9887 * 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
9888 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9889
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9890 @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
9891 @unnumberedsubsubsec Example with incrementing counter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9892
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9893 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
9894 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
9895 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
9896
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9897 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9898 @c pebble diagram
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9899 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9900 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9901 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9902 *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9903 * *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9904 * * *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9905 * * * *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9906 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9907 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9908 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9909 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9910 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9911 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9912 @bullet{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9913 @bullet{} @bullet{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9914 @bullet{} @bullet{} @bullet{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9915 @bullet{} @bullet{} @bullet{} @bullet{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9916 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9917 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9918 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9919 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9920
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9921 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9922 (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
9923 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
9924
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9925 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
9926 triangle with 7 rows?
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 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
9929 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
9930 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
9931 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
9932 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
9933 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
9934 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
9935
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9936 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
9937 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
9938 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
9939 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
9940 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
9941 a more complex process once.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9942
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9943 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
9944 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
9945 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
9946 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
9947 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
9948
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9949 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
9950 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
9951 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
9952 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
9953 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
9954 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
9955 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
9956
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9957 @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
9958 @unnumberedsubsubsec The parts of the function definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9959
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9960 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
9961 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
9962 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
9963 the function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9964
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9965 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
9966 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
9967 called @code{number-of-rows}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9968
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9969 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
9970 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
9971 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
9972 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
9973
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9974 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
9975 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
9976 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
9977 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
9978 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
9979 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
9980 more rows left to add.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9981
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9982 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
9983 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
9984 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
9985 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
9986 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
9987 statement will look like this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9990 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9991 (let ((total 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9992 (row-number 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9993 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9994 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9995 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9996
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
9997 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
9998 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
9999 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
10000 @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
10001 (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
10002 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
10003 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
10004 equal to the number of rows.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10005
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10006 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10007 @findex <= @r{(less than or equal)}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10008 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
10009 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
10010 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
10011 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
10012
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10013 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10014 (<= row-number number-of-rows)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10015 @end smallexample
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 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
10018 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
10019 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
10020 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
10021 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
10022 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
10023 would be replaced by the appropriate expression.)
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10026 (setq total (+ total row-number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10027 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10028
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10029 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10030 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
10031 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
10032
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10033 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
10034 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
10035 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
10036 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
10037 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
10038 @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
10039 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
10040 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
10041 repetition of the loop.
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 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10044 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
10045 @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
10046
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10047 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10048 (setq row-number (1+ row-number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10049 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10050
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10051 @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
10052 @unnumberedsubsubsec Putting the function definition together
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10053
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10054 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
10055 put them together.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10056
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10057 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10058 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
10059
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10060 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10061 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10062 (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
10063 (setq total (+ total row-number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10064 (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
10065 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10066 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10067
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10068 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
10069 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
10070 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
10071
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10072 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
10073 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
10074 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
10075 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
10076 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
10077
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10078 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
10079 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
10080 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
10081 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
10082 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
10083 of the @code{let}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10084
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10085 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10086 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
10087
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10088 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10089 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10090 (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
10091 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10092 (let (@var{varlist})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10093 (while (@var{true-or-false-test})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10094 @var{body-of-while}@dots{} )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10095 @dots{} ) ; @r{Need final expression here.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10096 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10097 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10098
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10099 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
10100 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
10101 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
10102 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
10103 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
10104 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
10105 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
10106 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
10107 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
10108 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
10109
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10110 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
10111 @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
10112 @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
10113 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
10114 the last element:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10115
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10116 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10117 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10118 (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
10119 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10120 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10121
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10122 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10123 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
10124 looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10125
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10126 @smallexample
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 (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
10129 ; @r{ incrementing counter.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10130 "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
10131 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
10132 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
10133 The argument is NUMBER-OF-ROWS."
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10136 (let ((total 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10137 (row-number 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10138 (while (<= row-number number-of-rows)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10139 (setq total (+ total row-number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10140 (setq row-number (1+ row-number)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10141 total))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10142 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10143 @end smallexample
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 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10146 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
10147 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
10148
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10149 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10150 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10151 (triangle 4)
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 (triangle 7)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10154 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10155 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10158 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
10159 numbers is 28.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10160
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10161 @node Decrementing Loop, , Incrementing Loop, while
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10162 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10163 @subsection Loop with a Decrementing Counter
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 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
10166 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
10167 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
10168 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
10169 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
10170 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
10171 repeatedly.
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 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
10174 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
10175 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
10176 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
10177 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
10178 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
10179 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
10180
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10181 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10182 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
10183
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10184 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10185 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10186 (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
10187 @var{body}@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10188 (setq counter (1- counter))) ; @r{decrementer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10189 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10190 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10191
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10192 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10193 * Decrementing Example:: More pebbles on the beach.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10194 * 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
10195 * 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
10196 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10197
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10198 @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
10199 @unnumberedsubsubsec Example with decrementing counter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10201 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
10202 @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
10203
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10204 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
10205 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
10206 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
10207 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
10208 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
10209
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10210 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
10211 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
10212 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
10213 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
10214 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
10215 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
10216 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
10217 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
10218
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10219 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
10220 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
10221 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
10222 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
10223 the row.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10224
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10225 @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
10226 @unnumberedsubsubsec The parts of the function definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10227
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10228 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
10229 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
10230 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
10231 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
10232 @code{total}, respectively.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10233
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10234 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
10235 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
10236 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
10237 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
10238 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
10239 the longest row.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10240
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10241 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10242 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
10243 like this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10246 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10247 (let ((total 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10248 (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
10249 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10250 @end group
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 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
10254 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
10255 evaluating the following expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10256
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10257 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10258 (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
10259 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10260
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10261 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10262 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
10263 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
10264 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
10265 added to the total.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10266
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10267 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
10268 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
10269 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
10270 done with the following expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10271
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10272 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10273 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10274 (setq number-of-pebbles-in-row
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10275 (1- number-of-pebbles-in-row))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10276 @end group
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 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
10280 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
10281 the @code{while} loop is simply:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10282
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10283 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10284 (while (> number-of-pebbles-in-row 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10285 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10286
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10287 @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
10288 @unnumberedsubsubsec Putting the function definition together
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10289
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10290 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
10291 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
10292 variables is unneeded!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10293
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10294 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10295 The function definition looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10296
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10297 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10298 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10299 ;;; @r{First subtractive version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10300 (defun triangle (number-of-rows)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10301 "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
10302 (let ((total 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10303 (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
10304 (while (> number-of-pebbles-in-row 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10305 (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
10306 (setq number-of-pebbles-in-row
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10307 (1- number-of-pebbles-in-row)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10308 total))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10309 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10310 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10311
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10312 As written, this function works.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10313
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10314 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
10315
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10316 @cindex Argument as local variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10317 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
10318 @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
10319 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
10320 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
10321 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
10322 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
10323 @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
10324 @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
10325
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10326 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10327 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
10328
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10329 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10330 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10331 (defun triangle (number) ; @r{Second version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10332 "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
10333 (let ((total 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10334 (while (> number 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10335 (setq total (+ total number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10336 (setq number (1- number)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10337 total))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10338 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10339 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10340
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10341 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
10342
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10343 @enumerate
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 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
10346 correct number of times.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10347
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10348 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10349 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
10350 after being repeatedly evaluated.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10351
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10352 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10353 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
10354 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
10355 number of times.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10356 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10357
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10358 @node dolist dotimes, Recursion, while, Loops & Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10359 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10360 @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
10361
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10362 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
10363 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
10364 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
10365 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
10366
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10367 @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
10368 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
10369 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
10370 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
10371
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10372 @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
10373
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10374 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10375 * dolist::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10376 * dotimes::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10377 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10378
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10379 @node dolist, dotimes, dolist dotimes, dolist dotimes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10380 @unnumberedsubsubsec The @code{dolist} Macro
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10381 @findex dolist
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10382
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10383 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
10384 ``first'' ``second'' ``third'' becomes ``third'' ``second'' ``first''.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10385
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10386 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10387 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
10388
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10389 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10390 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10391 (setq animals '(gazelle giraffe lion tiger))
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 (reverse animals)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10394 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10395 @end smallexample
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10398 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10399 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
10400
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10401 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10402 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10403 (setq animals '(gazelle giraffe lion tiger))
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 (defun reverse-list-with-while (list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10406 "Using while, reverse the order of LIST."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10407 (let (value) ; make sure list starts empty
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10408 (while list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10409 (setq value (cons (car list) value))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10410 (setq list (cdr list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10411 value))
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 (reverse-list-with-while animals)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10414 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10415 @end smallexample
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10418 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10419 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
10420
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10421 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10422 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10423 (setq animals '(gazelle giraffe lion tiger))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10424
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10425 (defun reverse-list-with-dolist (list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10426 "Using dolist, reverse the order of LIST."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10427 (let (value) ; make sure list starts empty
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10428 (dolist (element list value)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10429 (setq value (cons element value)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10430
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10431 (reverse-list-with-dolist animals)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10432 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10433 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10434
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10435 @need 1250
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 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
10438 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
10439
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10440 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10441 (tiger lion giraffe gazelle)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10442 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10443
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10444 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10445 in the echo area.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10446
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10447 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
10448 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
10449 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
10450 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
10451 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
10452 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
10453 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
10454 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
10455
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10456 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
10457 the @w{@code{(setq list (cdr list))}}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10458 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
10459 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
10460 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
10461 the loop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10462
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10463 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
10464 @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
10465 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
10466
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10467 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
10468 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
10469 `@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
10470 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
10471 arguments.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10472
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10473 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
10474 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
10475 @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
10476 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
10477
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10478 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
10479 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
10480 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
10481 @code{value}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10482
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10483 @node dotimes, , dolist, dolist dotimes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10484 @unnumberedsubsubsec The @code{dotimes} Macro
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10485 @findex dotimes
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 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
10488 loops a specific number of times.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10489
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10490 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
10491 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
10492 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
10493 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
10494
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10495 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10496 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
10497 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
10498 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
10499 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
10500 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
10501
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10502 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10503 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10504 (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
10505 (dotimes (number 3 value)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10506 (setq value (cons number value))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10507
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10508 @result{} (2 1 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10509 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10510 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10511
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10512 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10513 @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
10514 @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
10515 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
10516
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10517 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10518 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
10519 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
10520
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10521 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10522 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10523 (defun triangle-using-dotimes (number-of-rows)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10524 "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
10525 (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
10526 (dotimes (number number-of-rows total)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10527 (setq total (+ total (1+ number))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10528
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10529 (triangle-using-dotimes 4)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10530 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10531 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10532
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10533 @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
10534 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10535 @section Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10536 @cindex Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10537
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10538 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
10539 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
10540 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
10541 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
10542 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
10543 a different `instance'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10544
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10545 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
10546 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
10547 arguments that the final instance will stop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10548
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10549 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10550 * Building Robots:: Same model, different serial number ...
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10551 * Recursive Definition Parts:: Walk until you stop ...
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10552 * 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
10553 * Recursive triangle function::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10554 * Recursion with cond::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10555 * Recursive Patterns:: Often used templates.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10556 * No Deferment:: Don't store up work ...
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10557 * No deferment solution::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10558 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10559
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10560 @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
10561 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10562 @subsection Building Robots: Extending the Metaphor
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10563 @cindex Building robots
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10564 @cindex Robots, building
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10565
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10566 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
10567 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
10568 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
10569 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
10570 passed different arguments than the first.
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 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
10573 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
10574 entity; but all are clones.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10575
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10576 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
10577 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
10578 when to stop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10579
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10580 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
10581
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10582 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
10583 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
10584 @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
10585 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
10586 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
10587 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
10588 but a different `serial number'.
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 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
10591 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
10592 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
10593 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
10594
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10595 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
10596 next; otherwise, the process will never stop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10597
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10598 @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
10599 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10600 @subsection The Parts of a Recursive Definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10601 @cindex Parts of a Recursive Definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10602 @cindex Recursive Definition Parts
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 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
10605 has three parts:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10606
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10607 @enumerate
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 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
10610 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
10611
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10612 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10613 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
10614 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
10615
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10616 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10617 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
10618 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
10619 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
10620 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
10621 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
10622 false after the correct number of repetitions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10623 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10624
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10625 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
10626 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
10627 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
10628 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
10629 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
10630
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10631 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10632 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
10633 pattern looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10634
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10635 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10636 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10637 (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
10638 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10639 (if @var{do-again-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10640 @var{body}@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10641 (@var{name-of-recursive-function}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10642 @var{next-step-expression})))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10643 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10644 @end smallexample
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 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
10647 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
10648
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10649 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
10650 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
10651
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10652 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
10653
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10654 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
10655 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
10656 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
10657 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
10658 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
10659
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10660 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
10661 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
10662
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10663 @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
10664 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10665 @subsection Recursion with a List
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10666
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10667 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
10668 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
10669 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
10670
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10671 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
10672 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
10673 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
10674 @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
10675 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
10676 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
10677
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10678 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
10679 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
10680 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
10681
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10682 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
10683 directly in Info.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10684
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10685 @findex print-elements-recursively
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10686 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10687 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10688 (setq animals '(gazelle giraffe lion tiger))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10689
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10690 (defun print-elements-recursively (list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10691 "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
10692 Uses recursion."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10693 (if list ; @r{do-again-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10694 (progn
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10695 (print (car list)) ; @r{body}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10696 (print-elements-recursively ; @r{recursive call}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10697 (cdr list))))) ; @r{next-step-expression}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10698
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10699 (print-elements-recursively animals)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10700 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10701 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10702
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10703 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
10704 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
10705 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
10706 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
10707 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
10708 @sc{cdr} of the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10709
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10710 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
10711 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
10712 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
10713 instance.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10714
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10715 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
10716 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
10717 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
10718
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10719 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
10720 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
10721 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
10722 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
10723 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
10724 the @sc{cdr} of the original list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10725
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10726 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
10727 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
10728 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
10729 but is a separate individual.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10730
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10731 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
10732 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
10733 works on a shorter list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10734
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10735 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
10736 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
10737 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
10738 @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
10739 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
10740
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10741 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10742 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
10743 @file{*scratch*} buffer, you see this result:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10746 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10747 giraffe
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10748
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10749 gazelle
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10750
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10751 lion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10752
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10753 tiger
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10754 nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10755 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10756 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10757
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10758 @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
10759 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10760 @subsection Recursion in Place of a Counter
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10761 @findex triangle-recursively
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10762
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10763 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10764 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
10765 be written recursively. It looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10766
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10767 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10768 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10769 (defun triangle-recursively (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10770 "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
10771 Uses recursion."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10772 (if (= number 1) ; @r{do-again-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10773 1 ; @r{then-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10774 (+ number ; @r{else-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10775 (triangle-recursively ; @r{recursive call}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10776 (1- number))))) ; @r{next-step-expression}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10777
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10778 (triangle-recursively 7)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10779 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10780 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10781
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10782 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10783 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
10784 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
10785 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
10786 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
10787
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10788 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
10789 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
10790 its argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10791
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10792 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10793 * Recursive Example arg of 1 or 2::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10794 * Recursive Example arg of 3 or 4::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10795 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10796
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10797 @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
10798 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10799 @unnumberedsubsubsec An argument of 1 or 2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10800 @end ifnottex
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 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
10803
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10804 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
10805 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
10806 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
10807 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
10808 one row has one pebble in it.)
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 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
10811 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
10812
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10813 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10814 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
10815 @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
10816 this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10819 (+ number (triangle-recursively (1- number)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10820 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10821
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10822 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
10823 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
10824 in detail:
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 @table @i
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10827 @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
10828
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10829 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
10830 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
10831
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10832 @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
10833
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10834 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
10835 @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
10836 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
10837 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
10838 function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10839
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10840 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
10841 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
10842 @code{triangle-recursively} returns 1.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10843
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10844 @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
10845
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10846 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
10847 starts with @code{+}; its value is 2.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10848
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10849 @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
10850
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10851 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
10852 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
10853 evaluation of @code{triangle-recursively} (Step 2).
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 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
10856 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
10857 pebbles in it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10858 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10859
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10860 @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
10861 @unnumberedsubsubsec An argument of 3 or 4
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10862
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10863 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
10864 3.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10865
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10866 @table @i
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10867 @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
10868
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10869 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
10870 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
10871 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
10872 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
10873 true.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10874
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10875 @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
10876
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10877 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
10878 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
10879
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10880 @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
10881
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10882 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
10883
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10884 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
10885 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
10886 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
10887
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10888 @item Step 4 @w{ } Evaluate the addition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10889
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10890 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
10891 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
10892 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10893
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10894 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10895 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
10896
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10897 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
10898 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
10899 called with an argument of 4:
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 @quotation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10902 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10903 In the recursive call, the evaluation of
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 (1- 4))
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10910 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10911 will return the value of evaluating
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10912
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10913 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10914 (triangle-recursively 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10915 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10918 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
10919 third line.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10920 @end quotation
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10923 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
10924
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10925 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
10926 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
10927 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
10928 evaluate itself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10929
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10930 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
10931 requires that operations be deferred.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10932
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10933 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
10934 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
10935 @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
10936 @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
10937 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
10938 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
10939 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
10940 @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
10941
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10942 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
10943 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
10944 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
10945 on.
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 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
10948 @ref{No Deferment, , Recursion without Deferments}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10949
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10950 @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
10951 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10952 @subsection Recursion Example Using @code{cond}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10953 @findex cond
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10954
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10955 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
10956 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
10957 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
10958 @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
10959
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10960 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
10961 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
10962 explaining it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10963
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10964 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10965 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
10966
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10967 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10968 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10969 (cond
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10970 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10971 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10972 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10973
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10974 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10975 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
10976
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10977 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10978 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
10979
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10980 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10981 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10982 (cond
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10983 (@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
10984 (@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
10985 (@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
10986 @dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10987 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10988 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10989
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10990 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
10991 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
10992 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
10993 @code{cond}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10994
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
10995 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
10996 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
10997 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
10998 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
10999 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
11000 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
11001 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
11002 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
11003 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
11004
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11005 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
11006 returns @code{nil}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11007
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11008 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11009 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
11010
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11011 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11012 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11013 (defun triangle-using-cond (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11014 (cond ((<= number 0) 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11015 ((= number 1) 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11016 ((> number 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11017 (+ number (triangle-using-cond (1- number))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11018 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11019 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11020
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11021 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11022 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
11023 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
11024 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
11025 1.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11026
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11027 @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
11028 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11029 @subsection Recursive Patterns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11030 @cindex Recursive Patterns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11031
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11032 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
11033 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
11034 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
11035
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11036 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11037 * Every::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11038 * Accumulate::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11039 * Keep::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11040 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11041
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11042 @node Every, Accumulate, Recursive Patterns, Recursive Patterns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11043 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11044 @unnumberedsubsubsec Recursive Pattern: @emph{every}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11045 @cindex Every, type of recursive pattern
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11046 @cindex Recursive pattern: every
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11047
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11048 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
11049 element of a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11050
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11051 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11052 The basic pattern is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11053
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11054 @itemize @bullet
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 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
11057 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11058 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
11059 @itemize @minus
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11060 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11061 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
11062 @sc{cdr}) of the list,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11063 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11064 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
11065 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
11066 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11067 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11068
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11069 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11070 Here is example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11071
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11072 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11073 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11074 (defun square-each (numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11075 "Square each of a NUMBERS LIST, recursively."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11076 (if (not numbers-list) ; do-again-test
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11077 nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11078 (cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11079 (* (car numbers-list) (car numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11080 (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
11081 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11082
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11083 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11084 (square-each '(1 2 3))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11085 @result{} (1 4 9)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11086 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11087 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11088
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11089 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11090 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11091 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
11092 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
11093 with the result of the recursive call.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11094
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11095 (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
11096 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
11097 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
11098 empty.)
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 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
11101 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
11102 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
11103 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
11104
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11105 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11106 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
11107
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11108 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11109 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11110 (setq animals '(gazelle giraffe lion tiger))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11111 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11112
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11113 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11114 (defun print-elements-recursively (list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11115 "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
11116 Uses recursion."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11117 (if list ; @r{do-again-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11118 (progn
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11119 (print (car list)) ; @r{body}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11120 (print-elements-recursively ; @r{recursive call}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11121 (cdr list))))) ; @r{next-step-expression}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11122
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11123 (print-elements-recursively animals)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11124 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11125 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11126
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11127 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11128 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
11129
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11130 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11131 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11132 If the list be empty, do nothing.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11133 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11134 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
11135 @itemize @minus
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11136 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11137 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
11138 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11139 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
11140 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11141 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11142
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11143 @node Accumulate, Keep, Every, Recursive Patterns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11144 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11145 @unnumberedsubsubsec Recursive Pattern: @emph{accumulate}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11146 @cindex Accumulate, type of recursive pattern
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11147 @cindex Recursive pattern: accumulate
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 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
11150 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
11151 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
11152 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
11153
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11154 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
11155 @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
11156
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11157 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11158 The pattern is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11159
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11160 @itemize @bullet
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 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
11163 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11164 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
11165 @itemize @minus
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11166 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11167 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
11168 some other combining function, with
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11169 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11170 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
11171 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11172 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11173
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11174 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11175 Here is an example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11176
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11177 @smallexample
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 (defun add-elements (numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11180 "Add the elements of NUMBERS-LIST together."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11181 (if (not numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11182 0
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11183 (+ (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
11184 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11185
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11186 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11187 (add-elements '(1 2 3 4))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11188 @result{} 10
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11189 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11190 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11191
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11192 @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
11193 accumulate pattern.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11194
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11195 @node Keep, , Accumulate, Recursive Patterns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11196 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11197 @unnumberedsubsubsec Recursive Pattern: @emph{keep}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11198 @cindex Keep, type of recursive pattern
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11199 @cindex Recursive pattern: keep
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 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
11202 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
11203 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
11204 meets a criterion.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11205
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11206 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
11207 skipped unless it meets a criterion.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11208
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11209 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11210 The pattern has three parts:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11211
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11212 @itemize @bullet
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 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
11215 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11216 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
11217 a test
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11218 @itemize @minus
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11219 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11220 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
11221 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11222 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
11223 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11224 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11225 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
11226 the test
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11227 @itemize @minus
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11228 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11229 skip on that element,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11230 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11231 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
11232 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11233 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11234
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11235 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11236 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
11237
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11238 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11239 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11240 (defun keep-three-letter-words (word-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11241 "Keep three letter words in WORD-LIST."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11242 (cond
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11243 ;; First do-again-test: stop-condition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11244 ((not word-list) nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11245
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11246 ;; Second do-again-test: when to act
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11247 ((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
11248 ;; 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
11249 (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
11250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11251 ;; 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
11252 ;; 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
11253 (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
11254 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11255
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11256 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11257 (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
11258 @result{} (one two six)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11259 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11260 @end smallexample
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 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
11263 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
11264
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11265 @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
11266 @subsection Recursion without Deferments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11267 @cindex Deferment in recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11268 @cindex Recursion without Deferments
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11269
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11270 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
11271 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
11272 deferred until all can be done.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11273
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11274 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11275 Here is the function definition:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11276
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11277 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11278 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11279 (defun triangle-recursively (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11280 "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
11281 Uses recursion."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11282 (if (= number 1) ; @r{do-again-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11283 1 ; @r{then-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11284 (+ number ; @r{else-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11285 (triangle-recursively ; @r{recursive call}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11286 (1- number))))) ; @r{next-step-expression}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11287 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11288 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11289
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11290 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
11291
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11292 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
11293 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
11294 @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
11295 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
11296
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11297 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11298 (+ 7 (triangle-recursively 6)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11299 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11300
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11301 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11302 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
11303 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
11304 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
11305 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
11306 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
11307 `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
11308 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
11309 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
11310
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11311 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
11312 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
11313 @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
11314 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
11315
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11316 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11317 Now the total is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11318
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11319 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11320 (+ 7 6 (triangle-recursively 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11321 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11322
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11323 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11324 And what happens next?
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11327 (+ 7 6 5 (triangle-recursively 4)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11328 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11329
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11330 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
11331 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
11332 asks it to make a calculation.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11333
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11334 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11335 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
11336
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11337 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11338 (+ 7 6 5 4 3 2 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11339 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11340
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11341 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
11342 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
11343 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
11344 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
11345 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
11346 more steps.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11347
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11348 @node No deferment solution, , No Deferment, Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11349 @subsection No Deferment Solution
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11350 @cindex No deferment solution
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11351 @cindex Defermentless solution
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11352 @cindex Solution without deferment
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 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
11355 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
11356 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
11357 `constant space'.}. This requires
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11358 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
11359 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
11360 function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11361
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11362 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
11363 does the work.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11364
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11365 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11366 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
11367 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
11368
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11369 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11370 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11371 (defun triangle-initialization (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11372 "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
11373 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
11374 duo that uses recursion."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11375 (triangle-recursive-helper 0 0 number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11376 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11377 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11378
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11379 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11380 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11381 (defun triangle-recursive-helper (sum counter number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11382 "Return SUM, using COUNTER, through NUMBER inclusive.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11383 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
11384 that uses recursion."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11385 (if (> counter number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11386 sum
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11387 (triangle-recursive-helper (+ sum counter) ; @r{sum}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11388 (1+ counter) ; @r{counter}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11389 number))) ; @r{number}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11390 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11391 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11392
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11393 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11394 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
11395 @code{triangle-initialization} with 2 rows:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11396
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11397 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11398 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11399 (triangle-initialization 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11400 @result{} 3
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11401 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11402 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11403
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11404 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
11405 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
11406 number of rows in the triangle.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11407
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11408 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
11409 initialization values. These values are changed when
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11410 @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
11411 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
11412 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
11413 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
11414 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
11415 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
11416 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
11417 @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
11418 `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
11419
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11420 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
11421 triangle will have one pebble in it!)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11422
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11423 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11424 @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
11425 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
11426 test whether @code{(> counter number)}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11427
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11428 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11429 (> 0 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11430 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11431
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11432 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11433 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11434 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
11435 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
11436
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11437 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11438 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11439 (triangle-recursive-helper
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11440 (+ 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
11441 (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
11442 number) ; @r{number stays the same}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11443 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11444 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11445
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11446 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11447 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11448 which will first compute:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11449
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11450 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11451 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11452 (triangle-recursive-helper (+ 0 0) ; @r{sum}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11453 (1+ 0) ; @r{counter}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11454 1) ; @r{number}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11455 @exdent which is:
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 (triangle-recursive-helper 0 1 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11458 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11459 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11460
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11461 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
11462 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
11463 new instance with new arguments.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11464
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11465 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11466 This new instance will be;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11467
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11468 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11469 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11470 (triangle-recursive-helper
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11471 (+ 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
11472 (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
11473 number) ; @r{number stays the same}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11474
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11475 @exdent which is:
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 (triangle-recursive-helper 1 2 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11478 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11479 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11480
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11481 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
11482 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
11483 expected.
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 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
11486 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
11487
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11488 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
11489
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11490 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11491 In stages, the instances called will be:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11492
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11493 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11494 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11495 @r{sum counter number}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11496 (triangle-recursive-helper 0 1 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11497
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11498 (triangle-recursive-helper 1 2 2)
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 (triangle-recursive-helper 3 3 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11501 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11502 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11503
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11504 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
11505 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
11506 which will be 3.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11507
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11508 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
11509 many resources in a computer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11510
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11511 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11512 @node Looping exercise, , Recursion, Loops & Recursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11513 @section Looping Exercise
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11514
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11515 @itemize @bullet
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 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
11518 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
11519
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11520 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11521 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
11522 adds the values.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11523
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11524 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11525 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
11526 using @code{cond}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11527
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11528 @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
11529 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11530 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
11531 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
11532 (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
11533 information, see
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11534 @ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11535 @ref{Indicating, , Indicating Definitions, texinfo}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11536 @end ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11537 @ifhtml
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11538 @ref{Indicating, , Indicating, texinfo, Texinfo Manual}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11539 @end ifhtml
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11540 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11541 ``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
11542 Documentation Format}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11543 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11544 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11545
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11546 @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
11547 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11548 @chapter Regular Expression Searches
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11549 @cindex Searches, illustrating
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11550 @cindex Regular expression searches
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11551 @cindex Patterns, searching for
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11552 @cindex Motion by sentence and paragraph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11553 @cindex Sentences, movement by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11554 @cindex Paragraphs, movement by
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11555
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11556 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
11557 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
11558 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
11559 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
11560 as `regexp'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11561
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11562 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
11563 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
11564 @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
11565 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
11566 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
11567 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
11568 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
11569 @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
11570 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
11571 that spot.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11572
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11573 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
11574 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
11575 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
11576 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
11577 @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
11578 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
11579 @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
11580 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
11581 introduces several new features.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11582
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11583 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11584 * 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
11585 * 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
11586 * 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
11587 * forward-paragraph:: A somewhat complex example.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11588 * 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
11589 * Regexp Review::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11590 * re-search Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11591 @end menu
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 @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
11594 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11595 @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
11596 @findex sentence-end
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 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
11599 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
11600
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11601 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
11602 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
11603 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
11604 the pattern should include the character set:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11605
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11606 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11607 [.?!]
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11608 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11609
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11610 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
11611 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
11612 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
11613 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
11614
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11615 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
11616 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
11617 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
11618 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
11619 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
11620 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
11621 items as alternatives.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11622
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11623 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11624 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
11625
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11626 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11627 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11628 \\($\\| \\| \\)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11629 ^ ^^
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11630 TAB SPC
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11631 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11632 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11633
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11634 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11635 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
11636 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
11637 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
11638
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11639 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
11640 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
11641 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
11642 parenthesis or the vertical bar, is special.
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 @need 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11645 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
11646 this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11647
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11648 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11649 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11650 [
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 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11653 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11654
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11655 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11656 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
11657 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
11658 @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
11659
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11660 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
11661 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
11662 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
11663 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
11664 expression that looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11665
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11666 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11667 []\"')@}]*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11668 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11669
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11670 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
11671 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
11672 @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
11673 three characters are @samp{'}, @samp{)}, and @samp{@}}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11674
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11675 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
11676 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
11677 @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
11678
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11679 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11680 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11681 sentence-end
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11682 @result{} "[.?!][]\"')@}]*\\($\\| \\| \\)[
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11683 ]*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11684 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11685 @end smallexample
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 @ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11688
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11689 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11690 (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
11691 literally in the pattern.)
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 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
11694
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11695 @table @code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11696 @item [.?!]
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11697 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
11698 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
11699 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
11700
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11701 @item []\"')@}]*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11702 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
11703 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
11704 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
11705 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
11706 @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
11707 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
11708 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
11709 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
11710 more times.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11711
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11712 @item \\($\\| \\| \\)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11713 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
11714 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
11715 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
11716 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
11717 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
11718 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
11719 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
11720 indicate what they are.
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 @item [@key{RET}]*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11723 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
11724 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
11725 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
11726 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
11727 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
11728 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11729
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11730 @end ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11731
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11732 @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
11733 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11734 @section The @code{re-search-forward} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11735 @findex re-search-forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11736
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11737 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
11738 @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
11739 @code{search-forward} Function}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11740
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11741 @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
11742 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
11743 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
11744 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
11745 @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
11746 is therefore a `side effect'.)
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 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
11749 four arguments:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11750
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11751 @enumerate
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 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
11754 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
11755
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11756 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11757 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
11758 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
11759
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11760 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11761 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
11762 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
11763 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
11764 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
11765 if the search succeeds.
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 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11768 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
11769 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
11770 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11771
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11772 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11773 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
11774
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11775 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11776 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11777 (re-search-forward "@var{regular-expression}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11778 @var{limit-of-search}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11779 @var{what-to-do-if-search-fails}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11780 @var{repeat-count})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11781 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11782 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11783
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11784 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
11785 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
11786 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
11787 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
11788 to.
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 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11791 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
11792 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
11793
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11794 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11795 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11796 "[.?!][]\"')@}]*\\($\\| \\| \\)[
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11797 ]*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11798 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11799 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11801 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11802 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
11803 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
11804 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
11805 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
11806
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11807 @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
11808 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11809 @section @code{forward-sentence}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11810 @findex forward-sentence
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11811
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11812 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
11813 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
11814 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
11815 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
11816 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
11817 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
11818
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11819 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11820 * Complete forward-sentence::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11821 * 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
11822 * 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
11823 @end menu
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 @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
11826 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11827 @unnumberedsubsec Complete @code{forward-sentence} function definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11828 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11829
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11830 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11831 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
11832
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11833 @smallexample
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 (defun forward-sentence (&optional arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11836 "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
11837 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
11838 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
11839 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
11840 terminates sentences as well."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11841 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11842 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11843 (interactive "p")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11844 (or arg (setq arg 1))
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-beg
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11847 (save-excursion (start-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-backward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11849 (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
11850 (goto-char (1- (match-end 0)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11851 (goto-char par-beg)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11852 (setq arg (1+ arg)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11853 (while (> arg 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11854 (let ((par-end
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11855 (save-excursion (end-of-paragraph-text) (point))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11856 (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
11857 (skip-chars-backward " \t\n")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11858 (goto-char par-end)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11859 (setq arg (1- arg))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11860 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11861 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11862
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11863 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
11864 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
11865 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
11866
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11867 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11868 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11869 (defun forward-sentence (&optional arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11870 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11871 (interactive "p")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11872 (or arg (setq arg 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11873 (while (< arg 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11874 @var{body-of-while-loop}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11875 (while (> arg 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11876 @var{body-of-while-loop}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11877 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11878 @end smallexample
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 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
11881 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
11882 expression, and @code{while} loops.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11883
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11884 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
11885
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11886 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
11887
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11888 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
11889 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
11890 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
11891 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
11892 @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
11893 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
11894 @code{nil}.
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 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
11897 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
11898 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
11899 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
11900
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11901 @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
11902 @unnumberedsubsec The @code{while} loops
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 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
11905 @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
11906 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
11907 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
11908 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
11909 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
11910 loop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11911
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11912 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11913 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
11914 looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11915
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11916 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11917 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11918 (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
11919 (let @var{varlist}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11920 (if (@var{true-or-false-test})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11921 @var{then-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11922 @var{else-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11923 (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
11924 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11925 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11926
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11927 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
11928 (@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
11929 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
11930 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
11931 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
11932 the loop repeats.
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 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
11935 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
11936 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
11937
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11938 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
11939 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
11940 @code{if} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11941
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11942 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11943 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
11944
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11945 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11946 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11947 (let ((par-end
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11948 (save-excursion (end-of-paragraph-text) (point))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11949 (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
11950 (skip-chars-backward " \t\n")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11951 (goto-char par-end)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11952 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11953 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11954
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11955 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
11956 @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
11957 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
11958 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
11959 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
11960
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11961 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
11962 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
11963 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
11964 evaluates the expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11965
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11966 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11967 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11968 (save-excursion (end-of-paragraph-text) (point))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11969 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11970 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11971
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11972 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11973 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
11974 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
11975 @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
11976 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
11977 @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
11978 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
11979 @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
11980
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11981 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11982 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
11983 expression that looks like this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11986 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11987 (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
11988 (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
11989 (goto-char par-end))) ; @r{else-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11990 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11991 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11992
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11993 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
11994 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
11995 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
11996 expression is the regular expression search.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11997
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
11998 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
11999 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
12000 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
12001
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12002 @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
12003 @unnumberedsubsec The regular expression search
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12004
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12005 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
12006 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
12007 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
12008 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
12009
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12010 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12011 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12012 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
12013 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
12014
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12015 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12016 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
12017 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
12018 successful.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12019 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12020
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12021 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12022 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
12023 @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
12024 conclusion of the search.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12025
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12026 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
12027 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
12028 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
12029 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
12030 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
12031 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
12032 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
12033 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
12034 usually a period.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12035
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12036 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
12037 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
12038 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
12039 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
12040 end of the paragraph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12041
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12042 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
12043 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
12044 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
12045 incorporating this pattern often.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12046
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12047 @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
12048 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12049 @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
12050 @findex forward-paragraph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12051
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12052 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
12053 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
12054 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
12055 @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
12056
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12057 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
12058 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
12059 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
12060 fill prefix.
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 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
12063 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
12064 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
12065 @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
12066 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
12067 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
12068 prefixes.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12069
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12070 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
12071 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
12072 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
12073 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
12074 with the fill prefix.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12075
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12076 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
12077 exists, especially when blank lines separate paragraphs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12078 This is an added complication.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12079
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12080 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12081 * 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
12082 * fwd-para let:: The @code{let*} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12083 * 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
12084 * fwd-para between paragraphs:: Movement between paragraphs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12085 * fwd-para within paragraph:: Movement within paragraphs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12086 * 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
12087 * 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
12088 * 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
12089 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12090
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12091 @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
12092 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12093 @unnumberedsubsec Shortened @code{forward-paragraph} function definition
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12094 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12095
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12096 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
12097 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
12098 can be daunting!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12099
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12100 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12101 In outline, the function looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12102
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12103 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12104 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12105 (defun forward-paragraph (&optional arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12106 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12107 (interactive "p")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12108 (or arg (setq arg 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12109 (let*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12110 @var{varlist}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12111 (while (< arg 0) ; @r{backward-moving-code}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12112 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12113 (setq arg (1+ arg)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12114 (while (> arg 0) ; @r{forward-moving-code}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12115 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12116 (setq arg (1- arg)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12117 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12118 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12119
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12120 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
12121 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
12122
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12123 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
12124 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
12125 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
12126 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
12127 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
12128 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
12129 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
12130 @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
12131 familiar part of this function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12132
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12133 @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
12134 @unnumberedsubsec The @code{let*} expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12135
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12136 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
12137 @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
12138 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
12139
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12140 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
12141 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
12142 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
12143 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
12144
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12145 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
12146 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
12147 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
12148 value of @code{fill-prefix-regexp}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12149
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12150 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12151 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
12152 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
12153
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12154 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12155 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12156 (and fill-prefix
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12157 (not (equal fill-prefix ""))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12158 (not paragraph-ignore-fill-prefix)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12159 (regexp-quote fill-prefix))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12160 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12161 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12162
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12163 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12164 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
12165
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12166 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
12167 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
12168 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
12169 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
12170 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
12171 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
12172 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
12173 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
12174 arguments are true.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12175 @findex and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12176
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12177 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
12178 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
12179 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
12180 @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
12181
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12182 @table @code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12183 @item fill-prefix
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12184 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
12185 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
12186 @code{nil}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12187
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12188 @item (not (equal fill-prefix "")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12189 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
12190 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
12191 not a useful fill prefix.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12192
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12193 @item (not paragraph-ignore-fill-prefix)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12194 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
12195 @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
12196 true value such as @code{t}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12197
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12198 @item (regexp-quote fill-prefix)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12199 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
12200 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
12201 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
12202 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
12203 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12204
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12205 @findex regexp-quote
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12206 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12207 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
12208 @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
12209 @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
12210 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
12211 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
12212 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
12213 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
12214 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
12215
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12216 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
12217 @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
12218 evaluating the expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12219
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12220 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12221 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12222 (if fill-prefix-regexp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12223 (concat paragraph-separate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12224 "\\|^" fill-prefix-regexp "[ \t]*$")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12225 paragraph-separate)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12226 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12227 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12228
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12229 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
12230 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
12231 @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
12232
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12233 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
12234 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
12235 @code{paragraph-separate} to its local value.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12236 (@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
12237 separates paragraphs.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12238
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12239 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
12240 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
12241 @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
12242 @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
12243
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12244 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
12245 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
12246 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
12247 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
12248 @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
12249 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
12250 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
12251 @code{paragraph-separate}.
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 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
12254 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
12255 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
12256 section.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12257
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12258 @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
12259 @unnumberedsubsec The forward motion @code{while} loop
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12260
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12261 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
12262 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
12263 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
12264 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
12265 @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
12266 forward one paragraph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12267
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12268 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
12269 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
12270 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
12271
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12272 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12273 The @code{while} loop looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12274
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12275 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12276 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12277 (while (> arg 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12278 (beginning-of-line)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12279
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12280 ;; @r{between paragraphs}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12281 (while (prog1 (and (not (eobp))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12282 (looking-at paragraph-separate))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12283 (forward-line 1)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12284 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12285
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12286 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12287 ;; @r{within paragraphs, with a fill prefix}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12288 (if fill-prefix-regexp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12289 ;; @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
12290 (while (and (not (eobp))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12291 (not (looking-at paragraph-separate))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12292 (looking-at fill-prefix-regexp))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12293 (forward-line 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12294 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12295
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12296 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12297 ;; @r{within paragraphs, no fill prefix}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12298 (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
12299 (goto-char (match-beginning 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12300 (goto-char (point-max))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12301
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12302 (setq arg (1- arg)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12303 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12304 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12305
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12306 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
12307 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
12308
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12309 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12310 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
12311
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12312 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12313 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12314 ;; @r{between paragraphs}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12315 (beginning-of-line)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12316 (while
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12317 @var{body-of-while})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12318 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12319
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12320 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12321 ;; @r{within paragraphs, with fill prefix}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12322 (if @var{true-or-false-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12323 @var{then-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12324 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12325
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12326 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12327 ;; @r{within paragraphs, no fill prefix}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12328 @var{else-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12329 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12330 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12331
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12332 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12333 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
12334 @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
12335 @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
12336 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
12337 @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
12338 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
12339 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
12340 of the paragraph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12341
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12342 @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
12343 @unnumberedsubsec Between paragraphs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12344
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12345 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
12346 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
12347 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
12348 @findex prog1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12349 @findex eobp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12350 @findex looking-at
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12351
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12352 @itemize @bullet
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{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
12355 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
12356 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
12357 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
12358 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
12359 @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
12360
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12361 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12362 @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
12363 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
12364
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12365 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12366 @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
12367 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
12368 argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12369 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12370
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12371 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12372 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
12373
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12374 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12375 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12376 (while (prog1 (and (not (eobp))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12377 (looking-at paragraph-separate))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12378 (forward-line 1)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12379 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12380 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12381
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12382 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12383 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12384 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
12385 loop is the expression:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12388 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12389 (prog1 (and (not (eobp))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12390 (looking-at paragraph-separate))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12391 (forward-line 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12392 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12393 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12394
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12395 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12396 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
12397 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
12398 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
12399 expression for separating paragraphs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12400
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12401 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
12402 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
12403 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
12404 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
12405 @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
12406 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
12407 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
12408 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
12409 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
12410 @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
12411 @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
12412 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
12413 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
12414
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12415 @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
12416 @unnumberedsubsec Within paragraphs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12417
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12418 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
12419 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
12420 @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
12421 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
12422 @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
12423 fill prefix.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12424
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12425 @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
12426 @unnumberedsubsec No fill prefix
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12427
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12428 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
12429 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
12430 expression, and reads as follows:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12433 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12434 (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
12435 (goto-char (match-beginning 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12436 (goto-char (point-max)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12437 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12438 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12441 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
12442 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
12443 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
12444 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
12445 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
12446 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
12447
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12448 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
12449 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
12450 @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
12451 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
12452 expression search.
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 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
12455 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
12456 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
12457 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
12458 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
12459 @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
12460 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
12461
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12462 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
12463 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
12464 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
12465
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12466 @findex match-beginning
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12467 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
12468 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
12469 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
12470 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
12471 @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
12472 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
12473 of the paragraph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12474
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12475 (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
12476 @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
12477 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
12478
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12479 @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
12480 @unnumberedsubsec With a fill prefix
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12481
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12482 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
12483 @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
12484 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
12485 It looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12486
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12487 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12488 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12489 (while (and (not (eobp))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12490 (not (looking-at paragraph-separate))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12491 (looking-at fill-prefix-regexp))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12492 (forward-line 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12493 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12494 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12497 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
12498 as three conditions are true:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12499
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12500 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12501 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12502 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
12503
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12504 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12505 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
12506
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12507 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12508 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
12509 @end enumerate
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 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
12512 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
12513 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
12514 @code{looking-at} function will see it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12515
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12516 @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
12517 @unnumberedsubsec Summary
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12518
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12519 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
12520 does the following:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12521
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12522 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12523 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12524 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
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 Skip over lines between paragraphs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12528
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12529 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12530 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
12531
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12532 @itemize ---
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 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12535 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
12536 separating line.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12537 @end itemize
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 But if there is no fill prefix,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12541
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12542 @itemize ---
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12543
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12544 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12545 Search for the next paragraph start pattern.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12546
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12547 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12548 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
12549 end of the previous paragraph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12550
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12551 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12552 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
12553 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12554 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12555
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12556 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12557 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
12558 for clarity:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12559
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12560 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12561 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12562 (interactive "p")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12563 (or arg (setq arg 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12564 (let* (
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12565 (fill-prefix-regexp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12566 (and fill-prefix (not (equal fill-prefix ""))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12567 (not paragraph-ignore-fill-prefix)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12568 (regexp-quote fill-prefix)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12569 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12570
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12571 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12572 (paragraph-separate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12573 (if fill-prefix-regexp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12574 (concat paragraph-separate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12575 "\\|^"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12576 fill-prefix-regexp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12577 "[ \t]*$")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12578 paragraph-separate)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12579
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12580 @var{omitted-backward-moving-code} @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12581 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12582
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12583 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12584 (while (> arg 0) ; @r{forward-moving-code}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12585 (beginning-of-line)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12586
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12587 (while (prog1 (and (not (eobp))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12588 (looking-at paragraph-separate))
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
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12592 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12593 (if fill-prefix-regexp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12594 (while (and (not (eobp)) ; @r{then-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12595 (not (looking-at paragraph-separate))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12596 (looking-at fill-prefix-regexp))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12597 (forward-line 1))
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12600 ; @r{else-part: the inner-if}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12601 (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
12602 (goto-char (match-beginning 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12603 (goto-char (point-max))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12604
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12605 (setq arg (1- arg))))) ; @r{decrementer}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12606 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12607 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12608
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12609 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
12610 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
12611
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12612 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
12613 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
12614 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
12615 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
12616 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
12617 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
12618 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
12619 a car with his eyes shut!)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12620
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12621 @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
12622 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
12623 (@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
12624 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
12625 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
12626 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
12627 @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
12628 @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
12629
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12630 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
12631 lack one.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12632 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12633 @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
12634 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12635
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12636 @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
12637 @section Create Your Own @file{TAGS} File
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12638 @findex etags
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12639 @cindex @file{TAGS} file, create own
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 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
12642 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
12643 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
12644
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12645 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
12646 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
12647 the name is in upper case letters.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12648
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12649 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
12650 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
12651 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
12652 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
12653
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12654 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12655 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
12656 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
12657 @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
12658 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
12659 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
12660
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12661 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12662 M-x compile RET etags *.el RET
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12663 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12666 to create a @file{TAGS} file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12667
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12668 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
12669 @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
12670 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
12671 Lisp files in that directory.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12672
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12673 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12674 The @code{etags} program takes all the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12675 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
12676 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
12677 @w{@code{etags *.el ../elisp/*.el}},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12678 where @file{../elisp/} is the second directory:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12679
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12680 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12681 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
12682 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12683
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12684 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12685 Type
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12688 M-x compile RET etags --help RET
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12689 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12690
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12691 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12692 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
12693 list of supported languages.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12694
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12695 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
12696 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
12697 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
12698 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
12699 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
12700
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12701 @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
12702 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
12703 @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
12704 become part of the @file{TAGS} file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12705
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12706 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
12707 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
12708 program to attempt to find it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12709
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12710 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
12711 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
12712 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
12713 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
12714 files.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12715
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12716 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
12717 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
12718 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
12719 visit-tags-table}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12720
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12721 @subsubheading Building Tags in the Emacs sources
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12722 @cindex Building Tags in the Emacs sources
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12723 @cindex Tags in the Emacs sources
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12724 @findex make tags
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12725
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12726 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
12727 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
12728 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
12729 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
12730 level of your Emacs source directory.
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12733 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
12734 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
12735
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12736 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12737 M-x compile RET make tags RET
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12738 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12739
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12740 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12741 (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
12742 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
12743
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12744 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
12745 Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12746
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12747 @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
12748 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12749 @section Review
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 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
12752
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12753 @table @code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12754 @item while
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12755 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
12756 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
12757 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
12758
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12759 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12760 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12761
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12762 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12763 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12764 (let ((foo 2))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12765 (while (> foo 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12766 (insert (format "foo is %d.\n" foo))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12767 (setq foo (1- foo))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12768
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12769 @result{} foo is 2.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12770 foo is 1.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12771 nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12772 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12773 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12774 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12775 (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
12776 @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
12777 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
12778 line.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12779
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12780 @item re-search-forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12781 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
12782 just after it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12783
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12784 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12785 Takes four arguments, like @code{search-forward}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12786
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12787 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12788 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12789 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
12790
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12791 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12792 Optionally, the limit of the search.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12793
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12794 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12795 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
12796 error message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12797
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12798 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12799 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
12800 search goes backwards.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12801 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12802
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12803 @item let*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12804 Bind some variables locally to particular values,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12805 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
12806 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
12807 variables bound earlier, if any.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12808
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12809 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12810 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12811
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12812 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12813 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12814 (let* ((foo 7)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12815 (bar (* 3 foo)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12816 (message "`bar' is %d." bar))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12817 @result{} `bar' is 21.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12818 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12819 @end smallexample
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 match-beginning
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12822 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
12823 expression search.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12824
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12825 @item looking-at
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12826 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
12827 which should be a regular expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12828
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12829 @item eobp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12830 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
12831 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
12832 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
12833 the buffer is narrowed.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12834
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12835 @item prog1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12836 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
12837 @emph{first}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12838
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12839 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12840 For example:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12843 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12844 (prog1 1 2 3 4)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12845 @result{} 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12846 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12847 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12848 @end table
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12849
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12850 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12851 @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
12852 @section Exercises with @code{re-search-forward}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12853
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12854 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12855 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12856 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
12857 or more blank lines in sequence.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12858
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12859 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12860 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
12861 @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
12862 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
12863 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
12864 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
12865 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
12866 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
12867 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12868
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12869 @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
12870 @chapter Counting: Repetition and Regexps
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12871 @cindex Repetition for word counting
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12872 @cindex Regular expressions for word counting
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12873
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12874 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
12875 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
12876 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
12877 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
12878
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12879 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12880 * Why Count Words::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12881 * 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
12882 * 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
12883 * Counting Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12884 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12885
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12886 @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
12887 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12888 @unnumberedsec Counting words
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12889 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12890
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12891 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
12892 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
12893 function for counting words.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12894
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12895 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
12896 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
12897 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
12898 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
12899 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
12900 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
12901 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
12902 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
12903 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
12904 commands to count words.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12905
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12906 @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
12907 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12908 @section The @code{count-words-region} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12909 @findex count-words-region
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12910
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12911 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
12912 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
12913 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
12914 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
12915 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
12916 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
12917 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
12918 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
12919 h} (@code{mark-whole-buffer}).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12920
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12921 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
12922 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
12923 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
12924 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
12925 or to a @code{while} loop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12926
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12927 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12928 * 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
12929 * 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
12930 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12931
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12932 @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
12933 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12934 @unnumberedsubsec Designing @code{count-words-region}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12935 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12936
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12937 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
12938 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
12939 interactive.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12940
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12941 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12942 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
12943
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12944 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12945 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12946 (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
12947 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12948 (@var{interactive-expression}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12949 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12950 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12951 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12952
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12953 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
12954
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12955 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
12956 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
12957 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
12958
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12959 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
12960 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
12961 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
12962 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
12963 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
12964 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
12965 @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
12966 @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
12967 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
12968 this is routine.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12969
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12970 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
12971 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
12972 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
12973 a message to the user.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12974
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12975 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
12976 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
12977 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
12978 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
12979 @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
12980 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
12981 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
12982 @code{save-excursion} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12983
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12984 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
12985 @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
12986 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
12987 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
12988 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
12989
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12990 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
12991 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
12992 `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
12993
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12994 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
12995 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
12996 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
12997 word by word.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12998
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
12999 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
13000 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
13001 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
13002 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
13003 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
13004 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
13005 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
13006 the regexp must be optional.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13007
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13008 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
13009 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
13010 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
13011 this is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13012
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13013 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13014 \w+\W*
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13015 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13016
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13017 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13018 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
13019 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
13020 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
13021 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
13022 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
13023
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13024 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13025 The search expression looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13026
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13027 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13028 (re-search-forward "\\w+\\W*")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13029 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13032 (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
13033 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
13034 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
13035 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
13036 @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
13037 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
13038
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13039 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
13040 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
13041 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
13042
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13043 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13044 (setq count (1+ count))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13045 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13046
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13047 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
13048 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
13049 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
13050 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
13051 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
13052 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
13053 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
13054 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
13055 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
13056 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
13057 special form is appropriate.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13058
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13059 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13060 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
13061
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13062 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13063 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13064 ;;; @r{First version; has bugs!}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13065 (defun count-words-region (beginning end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13066 "Print number of words in the region.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13067 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
13068 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
13069 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
13070 table determines which characters these are."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13071 (interactive "r")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13072 (message "Counting words in region ... ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13073 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13074
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13075 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13076 ;;; @r{1. Set up appropriate conditions.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13077 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13078 (goto-char beginning)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13079 (let ((count 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13080 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13081
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13082 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13083 ;;; @r{2. Run the} while @r{loop.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13084 (while (< (point) end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13085 (re-search-forward "\\w+\\W*")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13086 (setq count (1+ count)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13087 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13088
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13089 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13090 ;;; @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
13091 (cond ((zerop count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13092 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13093 "The region does NOT have any words."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13094 ((= 1 count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13095 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13096 "The region has 1 word."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13097 (t
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13098 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13099 "The region has %d words." count))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13100 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13101 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13102
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13103 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13104 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
13105
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13106 @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
13107 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13108 @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
13109
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13110 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
13111 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
13112 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
13113 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
13114 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
13115 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
13116 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
13117 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13118
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13119 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13120 Search failed: "\\w+\\W*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13121 @end smallexample
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 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
13124 bugs yourself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13125
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13126 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
13127 @ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13128 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
13129 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
13130
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13131 @smallexample
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 ;; @r{First version; has bugs!}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13134 (defun count-words-region (beginning end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13135 "Print number of words in the region.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13136 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
13137 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
13138 syntax table determines which characters these are."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13139 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13140 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13141 (interactive "r")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13142 (message "Counting words in region ... ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13143 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13144
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13145 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13146 ;;; @r{1. Set up appropriate conditions.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13147 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13148 (goto-char beginning)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13149 (let ((count 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13150 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13151
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13152 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13153 ;;; @r{2. Run the} while @r{loop.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13154 (while (< (point) end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13155 (re-search-forward "\\w+\\W*")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13156 (setq count (1+ 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
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13159 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13160 ;;; @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
13161 (cond ((zerop count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13162 (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
13163 ((= 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
13164 (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
13165 @end group
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 @end ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13168
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13169 @need 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13170 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
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 (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
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 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
13177 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
13178 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
13179
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13180 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13181 one two three
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13182 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13183
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13184 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13185 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
13186
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13187 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
13188 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
13189 @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
13190 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
13191 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
13192 that the region has one word!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13193
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13194 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
13195 @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
13196 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
13197 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
13198 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
13199 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
13200 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
13201 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
13202
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13203 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
13204
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13205 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
13206 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
13207 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
13208 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
13209 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
13210 @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
13211 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
13212 @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
13213 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
13214 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
13215 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
13216 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
13217 the marked region.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13218
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13219 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
13220 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
13221 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
13222 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
13223 in the buffer, the search fails.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13224
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13225 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
13226 extend outside of the region.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13227
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13228 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
13229 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
13230 simple as you might think.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13231
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13232 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
13233 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
13234 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
13235 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
13236 @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
13237 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
13238 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
13239 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
13240
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13241 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
13242 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
13243 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
13244 to the regular expression search expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13245
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13246 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13247 (re-search-forward "\\w+\\W*" end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13248 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13249
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13250 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
13251 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
13252 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
13253 @samp{Search failed}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13254
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13255 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
13256 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
13257 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
13258 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
13259 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
13260
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13261 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
13262 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
13263 @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
13264
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13265 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
13266 ``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
13267 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
13268
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13269 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
13270 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
13271 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
13272 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
13273 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
13274 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
13275 @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
13276 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
13277 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
13278 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
13279 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
13280
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13281 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
13282 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
13283 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
13284 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
13285 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
13286 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
13287
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13288 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
13289 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
13290 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
13291 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
13292
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13293 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13294 (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
13295 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13296
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13297 @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
13298 @c also trouble with an overfull hbox
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13299 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13300 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13301 (For information about @code{and}, see
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13302 @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
13303 Functions}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13304 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13305 @ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13306 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13307 (@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
13308 @end ifinfo
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 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
13311 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
13312 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
13313 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
13314 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
13315 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
13316 or other of its messages.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13317
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13318 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
13319 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
13320 Here is what it looks like:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13321
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13322 @smallexample
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{Final version:} @code{while}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13325 (defun count-words-region (beginning end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13326 "Print number of words in the region."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13327 (interactive "r")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13328 (message "Counting words in region ... ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13329 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13330
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13331 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13332 ;;; @r{1. Set up appropriate conditions.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13333 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13334 (let ((count 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13335 (goto-char beginning)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13336 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13337
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13338 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13339 ;;; @r{2. Run the} while @r{loop.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13340 (while (and (< (point) end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13341 (re-search-forward "\\w+\\W*" end t))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13342 (setq count (1+ count)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13343 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13344
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13345 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13346 ;;; @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
13347 (cond ((zerop count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13348 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13349 "The region does NOT have any words."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13350 ((= 1 count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13351 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13352 "The region has 1 word."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13353 (t
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13354 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13355 "The region has %d words." count))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13356 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13357 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13358
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13359 @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
13360 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13361 @section Count Words Recursively
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13362 @cindex Count words recursively
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13363 @cindex Recursively counting words
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13364 @cindex Words, counted recursively
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 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
13367 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
13368
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13369 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
13370 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
13371 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
13372 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
13373
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13374 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
13375 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
13376 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
13377 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
13378 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
13379 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
13380 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
13381
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13382 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
13383 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
13384
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13385 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
13386 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
13387 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
13388 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
13389
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13390 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13391 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
13392 previous versions:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13393
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13394 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13395 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13396 ;; @r{Recursive version; uses regular expression search}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13397 (defun count-words-region (beginning end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13398 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13399 (@var{interactive-expression}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13400 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13401 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13402
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13403 ;;; @r{1. Set up appropriate conditions.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13404 (@var{explanatory message})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13405 (@var{set-up functions}@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13406 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13407 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13408
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13409 ;;; @r{2. Count the words.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13410 @var{recursive call}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13411 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13412 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13413
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13414 ;;; @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
13415 @var{message providing word count}))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13416 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13417 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13418
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13419 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
13420 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
13421 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
13422 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
13423 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
13424 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
13425 @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
13426 user.
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 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
13429 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
13430 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
13431 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
13432
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13433 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13434 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
13435
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13436 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13437 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13438 (defun count-words-region (beginning end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13439 "Print number of words in the region."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13440 (interactive "r")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13441 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13442
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13443 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13444 ;;; @r{1. Set up appropriate conditions.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13445 (message "Counting words in region ... ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13446 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13447 (goto-char beginning)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13448 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13449
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13450 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13451 ;;; @r{2. Count the words.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13452 (let ((count (recursive-count-words end)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13453 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13454
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13455 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13456 ;;; @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
13457 (cond ((zerop count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13458 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13459 "The region does NOT have any words."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13460 ((= 1 count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13461 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13462 "The region has 1 word."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13463 (t
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13464 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13465 "The region has %d words." count))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13466 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13467 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13468
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13469 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
13470
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13471 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
13472 `next-step-expression', and the recursive call.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13473
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13474 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
13475 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
13476 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
13477 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
13478 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
13479 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
13480 @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
13481 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
13482 argument.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13483
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13484 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
13485 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
13486
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13487 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
13488 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
13489 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
13490 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
13491 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
13492 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
13493
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13494 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
13495
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13496 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
13497 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
13498
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13499 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13500 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
13501
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13502 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13503 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13504 (defun recursive-count-words (region-end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13505 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13506 @var{do-again-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13507 @var{next-step-expression}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13508 @var{recursive call})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13509 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13510 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13511
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13512 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
13513 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
13514 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
13515 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
13516 function should return zero.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13517
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13518 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
13519 succeeds, the function should call itself again.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13520
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13521 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13522 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
13523
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13524 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13525 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13526 (and (< (point) region-end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13527 (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
13528 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13529 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13530
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13531 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
13532 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
13533 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
13534 @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
13535 @code{re-search-forward} works.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13536
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13537 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
13538 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
13539 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
13540 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
13541 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
13542
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13543 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
13544 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
13545 part of the do-again-test.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13546
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13547 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
13548 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
13549 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
13550 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
13551 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
13552 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
13553
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13554 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13555 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
13556 function looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13557
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13558 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13559 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13560 (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
13561 ;; @r{then}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13562 @var{recursive-call-returning-count}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13563 ;; @r{else}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13564 @var{return-zero})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13565 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13566 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13567
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13568 How to incorporate the mechanism that counts?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13569
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13570 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
13571 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
13572 systematically.
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 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
13575 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
13576 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
13577 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
13578 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
13579
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13580 Consider several cases:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13581
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13582 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13583 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13584 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
13585 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
13586 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
13587 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
13588
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13589 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13590 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
13591 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
13592 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
13593 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
13594
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13595 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13596 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
13597 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13598
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13599 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
13600 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
13601 @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
13602 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
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 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
13606 adds one to its argument.
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 (1+ (recursive-count-words region-end))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13610 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13611
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13612 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13613 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
13614 this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13615
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13616 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13617 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13618 (defun recursive-count-words (region-end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13619 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13620
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13621 ;;; @r{1. do-again-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13622 (if (and (< (point) region-end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13623 (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
13624 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13625
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13626 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13627 ;;; @r{2. then-part: the recursive call}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13628 (1+ (recursive-count-words region-end))
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 ;;; @r{3. else-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13631 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13632 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13633 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13634
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13635 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13636 Let's examine how this works:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13637
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13638 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
13639 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
13640
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13641 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
13642 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
13643 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
13644 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
13645 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
13646 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
13647 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
13648
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13649 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
13650 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
13651 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
13652 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
13653 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
13654 @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
13655 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
13656 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
13657
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13658 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
13659 @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
13660 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
13661 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
13662 the correct amount.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13663
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13664 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
13665 @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
13666 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
13667 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
13668
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13669 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13670 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13671 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
13672
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13673 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13674 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13675 The recursive function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13676
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13677 @findex recursive-count-words
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13678 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13679 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13680 (defun recursive-count-words (region-end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13681 "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
13682 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13683
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13684 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13685 ;;; @r{1. do-again-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13686 (if (and (< (point) region-end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13687 (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
13688 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13689
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13690 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13691 ;;; @r{2. then-part: the recursive call}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13692 (1+ (recursive-count-words region-end))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13693
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13694 ;;; @r{3. else-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13695 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13696 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13697 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13698
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13699 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13700 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13701 The wrapper:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13702
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13703 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13704 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13705 ;;; @r{Recursive version}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13706 (defun count-words-region (beginning end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13707 "Print number of words in the region.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13708 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13709
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13710 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13711 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
13712 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
13713 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
13714 determines which characters these are."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13715 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13716 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13717 (interactive "r")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13718 (message "Counting words in region ... ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13719 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13720 (goto-char beginning)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13721 (let ((count (recursive-count-words end)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13722 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13723 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13724 (cond ((zerop count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13725 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13726 "The region does NOT have any words."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13727 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13728 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13729 ((= 1 count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13730 (message "The region has 1 word."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13731 (t
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13732 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13733 "The region has %d words." count))))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13734 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13735 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13736
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13737 @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
13738 @section Exercise: Counting Punctuation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13739
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13740 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
13741 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
13742 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
13743
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13744 @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
13745 @chapter Counting Words in a @code{defun}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13746 @cindex Counting words in a @code{defun}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13747 @cindex Word counting in a @code{defun}
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 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
13750 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
13751 @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
13752 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
13753 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
13754 @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
13755 @code{count-word-region}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13756
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13757 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
13758 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
13759 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
13760 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
13761 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
13762 and this will tell.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13763
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13764 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13765 * Divide and Conquer::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13766 * Words and Symbols:: What to count?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13767 * Syntax:: What constitutes a word or symbol?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13768 * 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
13769 * 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
13770 * 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
13771 * 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
13772 * 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
13773 * 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
13774 * 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
13775 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13776
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13777 @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
13778 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13779 @unnumberedsec Divide and Conquer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13780 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13781
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13782 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
13783 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
13784 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
13785 steps must be:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13786
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13787 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13788 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13789 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
13790 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
13791
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13792 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13793 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
13794 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
13795 function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13796
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13797 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13798 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
13799 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
13800 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
13801 definitions within them.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13802
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13803 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13804 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
13805 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
13806 a graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13807
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13808 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13809 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
13810 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13811
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13812 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
13813 be difficult.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13814
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13815 @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
13816 @section What to Count?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13817 @cindex Words and symbols in defun
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13818
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13819 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
13820 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
13821 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
13822 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
13823 `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
13824 function contains the five symbols @code{defun},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13825 @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
13826 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
13827 @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
13828 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
13829 of ten words and symbols.
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13832 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13833 (defun multiply-by-seven (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13834 "Multiply NUMBER by seven."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13835 (* 7 number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13836 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13837 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13838
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13839 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13840 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
13841 @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
13842 @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
13843 @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
13844 ten! Something is wrong!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13845
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13846 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
13847 @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
13848 @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
13849 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
13850 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
13851 @samp{multiply by seven}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13852
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13853 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
13854 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
13855 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
13856 regexp is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13857
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13858 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13859 "\\w+\\W*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13860 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13861
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13862 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13863 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
13864 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
13865 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
13866 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
13867 of its own.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13868
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13869 @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
13870 @section What Constitutes a Word or Symbol?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13871 @cindex Syntax categories and tables
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13872
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13873 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
13874 @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
13875 @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
13876 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
13877 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
13878 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
13879 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
13880 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
13881 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
13882 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
13883
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13884 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
13885 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
13886 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
13887 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
13888 @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
13889 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
13890 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
13891
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13892 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
13893 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
13894
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13895 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
13896 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
13897 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
13898 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
13899 constituent character; there are others, too.
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 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
13902 @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
13903 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
13904
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13905 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13906 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
13907 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
13908
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13909 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13910 "\\(\\w\\|\\s_\\)+"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13911 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13912
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13913 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13914 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
13915 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
13916 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
13917 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
13918 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
13919 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
13920 characters must be matched at least once.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13921
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13922 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
13923 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
13924 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
13925 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
13926
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13927 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13928 "\\(\\W\\|\\S_\\)*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13929 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13930
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13931 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13932 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
13933 @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
13934 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
13935 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
13936
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13937 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
13938 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
13939 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
13940 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
13941 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
13942 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
13943 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
13944 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
13945 then followed optionally by white space.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13946
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13947 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13948 Here is the full regular expression:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13951 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13952 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13953
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13954 @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
13955 @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
13956 @cindex Counting words in a @code{defun}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13957
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13958 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
13959 @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
13960 @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
13961 versions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13962
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13963 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
13964 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
13965 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
13966 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
13967 simplify the definition a little.
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 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
13970 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
13971 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
13972 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
13973 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
13974 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
13975 function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13976
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13977 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13978 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
13979
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13980 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13981 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13982 (defun count-words-in-defun ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13983 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13984 (@var{set up}@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13985 (@var{while loop}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13986 @var{return count})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13987 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13988 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13989
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13990 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13991 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
13992
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13993 First, the set up.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13994
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
13995 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
13996 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
13997 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
13998 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
13999 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
14000 end of the definition.
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{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
14003 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
14004 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
14005 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
14006 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
14007 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
14008 place point where we wish to start.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14009
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14010 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
14011 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
14012 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
14013
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14014 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
14015 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
14016 @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
14017 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
14018
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14019 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
14020 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
14021 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
14022 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
14023 looping.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14024
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14025 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14026 The code looks like this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14029 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14030 (beginning-of-defun)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14031 (let ((count 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14032 (end (save-excursion (end-of-defun) (point))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14033 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14034 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14035
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14036 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14037 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
14038 @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
14039 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
14040 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
14041 definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14042
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14043 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
14044 is the @code{while} loop.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14045
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14046 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
14047 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
14048 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
14049 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
14050 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
14051 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
14052
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14053 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14054 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14055 (while (and (< (point) end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14056 (re-search-forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14057 "\\(\\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
14058 (setq count (1+ count)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14059 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14060 @end smallexample
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 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
14063 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
14064 @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
14065 @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
14066
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14067 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14068 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
14069
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14070 @findex count-words-in-defun
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14071 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14072 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14073 (defun count-words-in-defun ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14074 "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
14075 (beginning-of-defun)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14076 (let ((count 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14077 (end (save-excursion (end-of-defun) (point))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14078 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14079 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14080 (while
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14081 (and (< (point) end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14082 (re-search-forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14083 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14084 end t))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14085 (setq count (1+ count)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14086 count))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14087 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14088 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14089
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14090 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
14091 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
14092 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
14093 @code{count-words-region}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14094
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14095 @smallexample
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 ;;; @r{Interactive version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14098 (defun count-words-defun ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14099 "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
14100 (interactive)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14101 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14102 "Counting words and symbols in function definition ... ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14103 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14104 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14105 (let ((count (count-words-in-defun)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14106 (cond
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14107 ((zerop count)
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 does NOT have any words or symbols."))
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14112 ((= 1 count)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14113 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14114 "The definition has 1 word or symbol."))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14115 (t
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14116 (message
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14117 "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
14118 @end group
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14122 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14123 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
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 (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
14127 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14128
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14129 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
14130 @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
14131 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
14132
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14133 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14134 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14135 (defun multiply-by-seven (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14136 "Multiply NUMBER by seven."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14137 (* 7 number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14138 @result{} 10
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14139 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14140 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14141
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14142 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14143 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
14144
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14145 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
14146 several definitions within a single 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 @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
14149 @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
14150
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14151 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
14152 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
14153 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
14154 statistics on one file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14155
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14156 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
14157 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
14158
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14159 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
14160 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
14161 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
14162 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
14163 messages.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14164
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14165 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
14166 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
14167 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
14168 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
14169 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
14170
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14171 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
14172 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
14173 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
14174 (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
14175 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
14176 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
14177 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
14178 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
14179 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
14180 is almost all there is to it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14181
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14182 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14183 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
14184
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14185 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14186 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14187 (goto-char (point-min))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14188 (while (re-search-forward "^(defun" nil t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14189 (setq lengths-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14190 (cons (count-words-in-defun) lengths-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14191 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14192 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14193
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14194 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
14195 contains the function definitions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14196
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14197 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
14198 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
14199 @file{*scratch*} buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14201 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
14202
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14203 @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
14204 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14205 @section Find a File
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14206 @cindex Find a File
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14207
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14208 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
14209 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
14210 problem.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14211
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14212 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14213 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
14214 @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
14215 find the source of a function):
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14216
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14217 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14218 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14219 (defun find-file (filename)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14220 "Edit file FILENAME.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14221 Switch to a buffer visiting file FILENAME,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14222 creating one if none already exists."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14223 (interactive "FFind file: ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14224 (switch-to-buffer (find-file-noselect filename)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14225 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14226 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14227
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14228 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
14229 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
14230 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
14231 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
14232
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14233 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
14234 @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
14235 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
14236 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
14237 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
14238 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
14239 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
14240 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
14241 buffer switching elsewhere. (@xref{Switching Buffers}.)
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 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
14244 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
14245 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
14246 @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
14247 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
14248 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
14249 our own expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14251 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
14252
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14253 @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
14254 @section @code{lengths-list-file} in Detail
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 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
14257 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
14258 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
14259 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
14260 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
14261 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
14262 @findex lengths-list-file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14263
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14264 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14265 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14266 (defun lengths-list-file (filename)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14267 "Return list of definitions' lengths within FILE.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14268 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
14269 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
14270 symbols in one function definition."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14271 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14272 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14273 (message "Working on `%s' ... " filename)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14274 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14275 (let ((buffer (find-file-noselect filename))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14276 (lengths-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14277 (set-buffer buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14278 (setq buffer-read-only t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14279 (widen)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14280 (goto-char (point-min))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14281 (while (re-search-forward "^(defun" nil t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14282 (setq lengths-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14283 (cons (count-words-in-defun) lengths-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14284 (kill-buffer buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14285 lengths-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14286 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14287 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14288
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14289 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14290 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
14291 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
14292 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
14293 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
14294 message.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14295
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14296 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
14297 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
14298 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
14299 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
14300
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14301 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
14302 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
14303 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
14304 variable.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14305
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14306 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
14307
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14308 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
14309 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
14310 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
14311 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
14312 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
14313 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
14314 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
14315 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
14316 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
14317 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
14318
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14319 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
14320 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
14321 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
14322 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
14323 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
14324 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
14325 won't.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14326
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14327 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
14328 beginning of the buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14329
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14330 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
14331 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
14332 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
14333
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14334 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
14335 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
14336 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
14337 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
14338 files.
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 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
14341 @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
14342 the whole function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14343
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14344 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
14345 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
14346 C-e} (@code{eval-last-sexp}).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14347
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14348 @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
14349 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14350 (lengths-list-file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14351 "/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
14352 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14353
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14354 @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
14355 @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
14356 @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
14357 @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
14358
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14359 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14360 (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
14361 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
14362 the @file{*scratch*} buffer and edit it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14363
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14364 @need 1200
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 (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
14367 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
14368
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14369 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14370 (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
14371 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14374 (@xref{defcustom, , Setting Variables with @code{defcustom}}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14375 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
14376
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14377 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14378 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
14379 produce and looks 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 (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
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 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14386 (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
14387 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
14388
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14389 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14390 (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
14391 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14392
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14393 (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
14394 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
14395
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14396 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
14397 the list.
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 @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
14400 @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
14401
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14402 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
14403 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
14404 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
14405 a list of files.
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 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
14408 either a @code{while} loop or recursion.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14409
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14410 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14411 * 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
14412 * append:: Attach one list to another.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14413 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14414
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14415 @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
14416 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14417 @unnumberedsubsec Determine the lengths of @code{defuns}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14418 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14419
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14420 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
14421 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
14422 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
14423 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
14424 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
14425 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
14426 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
14427 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
14428 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
14429
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14430 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14431 The template looks like this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14434 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14435 (while @var{test-whether-list-is-empty}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14436 @var{body}@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14437 @var{set-list-to-cdr-of-list})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14438 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14439 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14440
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14441 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
14442 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
14443 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
14444 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
14445 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
14446 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
14447 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
14448 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
14449 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
14450 Example with an Incrementing Counter}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14451
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14452 @findex lengths-list-many-files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14453 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14454 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
14455
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14456 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14457 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14458 ;;; @r{Use @code{while} loop.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14459 (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
14460 "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
14461 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14462 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14463 (let (lengths-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14464
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14465 ;;; @r{true-or-false-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14466 (while list-of-files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14467 (setq lengths-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14468 (append
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14469 lengths-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14470
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14471 ;;; @r{Generate a lengths' list.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14472 (lengths-list-file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14473 (expand-file-name (car list-of-files)))))
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
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14476 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14477 ;;; @r{Make files' list shorter.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14478 (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
14479
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14480 ;;; @r{Return final value of lengths' list.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14481 lengths-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14482 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14483 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14484
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14485 @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
14486 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
14487 the function is called.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14488
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14489 @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
14490 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14491 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
14492 Emacs is visiting the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14493 @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
14494
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14495 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14496 debug.el
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14497 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14498
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14499 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14500 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14501 becomes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14502
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14503 @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
14504 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14505 /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
14506 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14507
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14508 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
14509 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
14510 itself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14511
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14512 @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
14513 @subsection The @code{append} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14514
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14515 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14516 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
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 (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
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14523 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14524 produces the list
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 (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 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
14531 @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
14532 @code{cons},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14533
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14534 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14535 (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
14536 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14537
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14538 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14539 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14540 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
14541 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
14542
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14543 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14544 ((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
14545 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14546
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14547 @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
14548 @section Recursively Count Words in Different Files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14549
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14550 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
14551 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
14552 is short and simple.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14553
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14554 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
14555 `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
14556 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
14557 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
14558 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
14559 @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
14560 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
14561 function is shorter than this description!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14562 @findex recursive-lengths-list-many-files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14563
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14564 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14565 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14566 (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
14567 "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
14568 (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
14569 (append
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14570 (lengths-list-file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14571 (expand-file-name (car list-of-files)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14572 (recursive-lengths-list-many-files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14573 (cdr list-of-files)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14574 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14575 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14576
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14577 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14578 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
14579 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
14580 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
14581
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14582 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
14583 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
14584 individually.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14585
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14586 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
14587 @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
14588 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
14589 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
14590 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
14591 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
14592
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14593 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
14594 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
14595 Emacs may produce different results.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14596
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14597 @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
14598 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14599 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14600 (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
14601
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14602 (lengths-list-file "./lisp/macros.el")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14603 @result{} (273 263 456 90)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14604 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14605
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14606 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14607 (lengths-list-file "./lisp/mail/mailalias.el")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14608 @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
14609 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14610
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14611 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14612 (lengths-list-file "./lisp/makesum.el")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14613 @result{} (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
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14616 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14617 (recursive-lengths-list-many-files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14618 '("./lisp/macros.el"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14619 "./lisp/mail/mailalias.el"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14620 "./lisp/makesum.el"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14621 @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
14622 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14623 @end smallexample
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 produces the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14626 output we want.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14627
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14628 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
14629
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14630 @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
14631 @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
14632
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14633 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
14634 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
14635 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
14636 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
14637 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
14638 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
14639 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
14640
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14641 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
14642 @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
14643 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
14644 numbers.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14645
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14646 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
14647 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
14648 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
14649 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
14650
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14651 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
14652 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
14653 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
14654 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
14655 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
14656 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
14657 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
14658 that we will need.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14659
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14660 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14661 * Sorting:: Sorting lists.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14662 * Files List:: Making a list of files.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14663 * Counting function definitions::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14664 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14665
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14666 @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
14667 @subsection Sorting Lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14668 @findex sort
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14669
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14670 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
14671 @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
14672 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
14673 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
14674
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14675 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
14676 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
14677 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
14678 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
14679 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
14680 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
14681 alphabetize a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14682
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14683 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14684 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
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 (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
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14691 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14692 produces this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14693
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14694 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14695 (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
14696 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14697
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14698 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14699 (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
14700 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
14701 arguments.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14702
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14703 Sorting the list returned by the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14704 @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
14705 it uses the @code{<} function:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14708 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14709 (sort
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14710 (recursive-lengths-list-many-files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14711 '("../lisp/macros.el"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14712 "../lisp/mailalias.el"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14713 "../lisp/makesum.el"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14714 '<
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14715 @end group
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14719 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14720 which produces:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14721
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14722 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14723 (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
14724 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14727 (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
14728 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
14729 list that is passed to @code{sort}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14730
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14731 @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
14732 @subsection Making a List of Files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14733
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14734 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
14735 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
14736 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
14737 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
14738 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
14739 recursive call.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14740
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14741 @findex directory-files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14742 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
14743 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
14744 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
14745 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
14746 pattern within a single directory.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14747
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14748 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
14749 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
14750 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
14751 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
14752 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
14753 function that descends into the sub-directories.
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 @findex files-in-below-directory
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14756 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
14757 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
14758 @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
14759 @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
14760 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
14761 of sub-directories, but also their attributes.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14762
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14763 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
14764 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
14765 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
14766
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14767 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14768 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14769 ("../lisp/macros.el"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14770 "../lisp/mail/rmail.el"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14771 "../lisp/makesum.el")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14772 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14773 @end smallexample
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 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
14776 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
14777 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
14778 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
14779 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
14780 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
14781 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
14782
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14783 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
14784 is @file{abbrev.el}. Its name is
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14785 @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
14786 directory or a symbolic link.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14787
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14788 @need 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14789 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
14790 its attributes:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14791
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14792 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14793 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14794 ("/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
14795 nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14796 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14797 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14798 100
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14799 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14800 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14801 (15019 32380)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14802 (14883 48041)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14803 (15214 49336)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14804 11583
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14805 "-rw-rw-r--"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14806 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14807 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14808 t
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14809 341385
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14810 776)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14811 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14812 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14813
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14814 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14815 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
14816 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
14817
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14818 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14819 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14820 ("/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
14821 t
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14822 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14823 )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14824 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14825 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14826
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14827 (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
14828 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
14829 @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
14830 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
14831 element.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14832
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14833 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
14834 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
14835 any directories below that directory.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14836
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14837 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
14838 @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
14839 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
14840 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
14841 sub-directory and repeat its actions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14842
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14843 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
14844 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
14845 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
14846 @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
14847 @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
14848 @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
14849 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
14850 directory.
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 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
14853 several tasks:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14854
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14855 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14856 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14857 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
14858 @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
14859
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14860 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14861 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
14862 directory; and if so,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14863
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14864 @itemize @minus
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14865 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14866 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
14867 so skip it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14868
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14869 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14870 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
14871 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14872 @end itemize
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 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
14875 @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
14876 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
14877 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
14878 pattern is `accumulate'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14879 (@pxref{Accumulate, , Recursive Pattern: @emph{accumulate}}),
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14880 using @code{append} as the combiner.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14881
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14882 @ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14883 (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
14884 (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
14885 @end ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14886
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14887 @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
14888
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14889 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14890 Here is the function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14891
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14892 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14893 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14894 (defun files-in-below-directory (directory)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14895 "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
14896 ;; 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
14897 ;; 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
14898 ;; 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
14899 ;; "/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
14900 (interactive "DDirectory name: ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14901 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14902 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14903 (let (el-files-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14904 (current-directory-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14905 (directory-files-and-attributes directory t)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14906 ;; while we are in the current directory
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14907 (while current-directory-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 (cond
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14911 ;; 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
14912 ;; 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
14913 ((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
14914 (setq el-files-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14915 (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
14916 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14917 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14918 ;; 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
14919 ((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
14920 ;; decide whether to skip or recurse
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14921 (if
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14922 (equal (or "." "..")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14923 (substring (car (car current-directory-list)) -1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14924 ;; 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
14925 ;; current directory or parent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14926 ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14927 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14928 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14929 ;; 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
14930 (setq el-files-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14931 (append
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14932 (files-in-below-directory
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14933 (car (car current-directory-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14934 el-files-list)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14935 ;; 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
14936 ;; 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
14937 (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
14938 ;; return the filenames
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14939 el-files-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14940 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14941 @end smallexample
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 (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
14944
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14945 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
14946 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
14947
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14948 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14949 Thus, on my system,
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 @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
14952 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14953 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14954 (length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14955 (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
14956 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14957 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14960 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
14961 @samp{.el} files.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14962
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14963 @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
14964 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
14965 like this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14968 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14969 (sort
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14970 (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
14971 'string-lessp)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14972 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14973 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14974
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14975 @ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14976 (defun test ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14977 "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
14978 (insert "\n" (current-time-string) "\n")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14979 (sit-for 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14980 (sort
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14981 (recursive-lengths-list-many-files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14982 '("../lisp/macros.el"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14983 "../lisp/mailalias.el"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14984 "../lisp/makesum.el"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14985 '<)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14986 (insert (format "%s" (current-time-string))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14987
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14988 @end ignore
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 @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
14991 @subsection Counting function definitions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14992
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14993 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
14994 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
14995 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
14996 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
14997
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
14998 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
14999 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
15000 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
15001 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
15002 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
15003 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
15004 numbers the @code{top-of-ranges} list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15005
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15006 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15007 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
15008 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
15009 @vindex top-of-ranges
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15010
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15011 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15012 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15013 (defvar top-of-ranges
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15014 '(10 20 30 40 50
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15015 60 70 80 90 100
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15016 110 120 130 140 150
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15017 160 170 180 190 200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15018 210 220 230 240 250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15019 260 270 280 290 300)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15020 "List specifying ranges for `defuns-per-range'.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15021 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15022 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15023
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15024 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
15025
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15026 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
15027 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
15028 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
15029 as arguments.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15030
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15031 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
15032 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
15033 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
15034 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
15035 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
15036 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
15037 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
15038 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
15039 top-of-range values in turn.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15040
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15041 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
15042 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
15043 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
15044 small gear inside a big gear.
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 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
15047 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
15048 (@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
15049 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
15050 @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
15051 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
15052 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
15053
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15054 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15055 The inner loop looks like this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15058 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15059 (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
15060 (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
15061 (setq sorted-lengths (cdr sorted-lengths)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15062 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15063 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15064
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15065 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
15066 @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
15067 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
15068
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15069 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15070 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15071 (while top-of-ranges
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15072 @var{body-of-loop}@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15073 (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
15074 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15075 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15076
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15077 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15078 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
15079
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15080 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15081 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15082 (while top-of-ranges
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15083
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15084 ;; @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
15085 (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
15086 (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
15087 (setq sorted-lengths (cdr sorted-lengths)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15088
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15089 ;; @r{Move to next range.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15090 (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
15091 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15092 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15093
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15094 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
15095 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
15096 @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
15097 this purpose. (@xref{cons, , @code{cons}}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15098
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15099 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
15100 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
15101 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
15102 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
15103 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
15104 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
15105 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
15106 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
15107 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
15108 @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
15109 @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
15110 @findex nreverse
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15111
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15112 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15113 For example,
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 (nreverse '(1 2 3 4))
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15120 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15121 produces:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15122
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15123 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15124 (4 3 2 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15125 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15126
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15127 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
15128 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
15129 @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
15130 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
15131 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
15132 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
15133 as is.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15134 @findex reverse
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15135
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15136 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15137 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
15138
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15139 @smallexample
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 (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
15142 "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
15143 (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
15144 (number-within-range 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15145 defuns-per-range-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15146 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15147
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15148 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15149 ;; @r{Outer loop.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15150 (while top-of-ranges
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{Inner loop.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15155 (while (and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15156 ;; @r{Need number for numeric test.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15157 (car sorted-lengths)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15158 (< (car sorted-lengths) top-of-range))
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 ;; @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
15163 (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
15164 (setq sorted-lengths (cdr sorted-lengths)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15165
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15166 ;; @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
15167 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15168
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15169 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15170 (setq defuns-per-range-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15171 (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
15172 (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
15173 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15174
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15175 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15176 ;; @r{Move to next range.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15177 (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
15178 ;; @r{Specify next top of range value.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15179 (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
15180 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15181
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15182 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15183 ;; @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
15184 ;; @r{ the largest top-of-range value.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15185 (setq defuns-per-range-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15186 (cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15187 (length sorted-lengths)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15188 defuns-per-range-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15189 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15190
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15191 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15192 ;; @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
15193 ;; @r{ smallest to largest.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15194 (nreverse defuns-per-range-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15195 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15196 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15197
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15198 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15199 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15200 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
15201 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
15202
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15203 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15204 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15205 (and (car sorted-lengths)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15206 (< (car sorted-lengths) top-of-range))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15207 @end group
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15211 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15212 instead of like this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15215 (< (car sorted-lengths) top-of-range)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15216 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15217
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15218 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
15219 @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
15220 range.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15221
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15222 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
15223 @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
15224 @code{(car sorted-lengths)} expression function returns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15225 @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
15226 @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
15227 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
15228
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15229 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
15230 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
15231 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
15232 the test will fail.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15233
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15234 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
15235 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
15236 @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
15237 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
15238 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
15239 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
15240 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
15241 @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
15242 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
15243 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
15244 of the @code{and} expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15245
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15246 @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
15247 This way, we avoid an error.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15248 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15249 @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
15250 Functions}, for more information about @code{and}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15251 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15252 @ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15253 @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
15254 @end ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15255
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15256 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
15257 evaluate the expression that binds (a shortened)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15258 @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
15259 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
15260 evaluate the @code{defuns-per-range} function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15261
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15262 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15263 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15264 ;; @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
15265 (setq top-of-ranges
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15266 '(110 120 130 140 150
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15267 160 170 180 190 200))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15268
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15269 (setq sorted-lengths
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15270 '(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
15271
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15272 (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
15273 @end group
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15277 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15278 The list returned looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15279
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15280 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15281 (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
15282 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15285 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
15286 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
15287 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
15288 of 200 or larger.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15289
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15290 @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
15291
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15292 @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
15293 @chapter Readying a Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15294 @cindex Readying a graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15295 @cindex Graph prototype
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15296 @cindex Prototype graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15297 @cindex Body of graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15298
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15299 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
15300 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
15301
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15302 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
15303 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
15304 (@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
15305 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
15306 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
15307 more.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15308
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15309 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
15310 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
15311 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
15312 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
15313 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
15314 the function to label the axes automatically.
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 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15317 * Columns of a graph::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15318 * 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
15319 * recursive-graph-body-print::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15320 * Printed Axes::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15321 * Line Graph Exercise::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15322 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15323
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15324 @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
15325 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15326 @unnumberedsec Printing the Columns of a Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15327 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15328
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15329 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
15330 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
15331 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
15332 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
15333 symbol a user option.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15334
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15335 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
15336 @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
15337 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
15338
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15339 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
15340 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
15341 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
15342 @code{numbers-list}.
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 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
15345 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
15346
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15347 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
15348 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
15349 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
15350 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
15351
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15352 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
15353 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
15354 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
15355 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
15356 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
15357 @findex apropos
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15358
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15359 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
15360 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
15361 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
15362 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
15363 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
15364 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
15365 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
15366 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
15367
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15368 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15369 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
15370
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15371 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15372 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15373 insert-rectangle:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15374 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
15375 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
15376 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
15377 RECTANGLE should be a list of strings.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15378 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15379 @end smallexample
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 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
15382
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15383 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
15384 @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
15385 (@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
15386 @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
15387 point. Also the function returns @code{nil}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15388
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15389 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15390 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15391 (insert-rectangle '("first" "second" "third"))first
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15392 second
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15393 third
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15394 nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15395 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15396 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15399 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
15400 @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
15401 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
15402 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
15403 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
15404 column of strings.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15405
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15406 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
15407 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
15408 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
15409 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
15410 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
15411 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
15412 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
15413 is the keybinding for @code{eval-expression}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15414
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15415 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
15416 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
15417 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
15418 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
15419 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
15420 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
15421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15422 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
15423 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
15424 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
15425 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
15426 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
15427 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
15428 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
15429 right---or perhaps we can@dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15430
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15431 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
15432 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
15433 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
15434 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
15435 @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
15436 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
15437 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
15438 be difficult.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15439
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15440 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
15441 @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
15442 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
15443 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
15444 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
15445 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
15446 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
15447 @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
15448
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15449 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15450 (" " " " "*" "*" "*")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15451 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15452
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15453 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
15454 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
15455 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
15456 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
15457 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
15458 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
15459 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
15460 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
15461 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
15462 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
15463 example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15464
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15465 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15466 (max 3 4 6 5 7 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15467 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15468
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15469 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15470 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
15471 smallest of all its arguments.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15472 @findex max
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15473 @findex min
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 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
15476 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
15477 numbers. Thus, the following expression,
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 (max '(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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15484 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15485 produces the following error message;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15486
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15487 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15488 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
15489 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15490
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15491 @findex apply
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15492 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
15493 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
15494 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
15495 may be a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15496
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15497 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15498 For example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15499
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15500 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15501 (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
15502 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15503
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15504 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15505 returns 8.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15506
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15507 (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
15508 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
15509 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
15510 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
15511 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
15512 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
15513 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
15514 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
15515 it.)
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 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
15518 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
15519 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
15520
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15521 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15522 (apply 'max '(4 8 5))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15523 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15524
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15525 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
15526 @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
15527 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
15528 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
15529 sorted or not.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15530
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15531 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15532 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
15533
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15534 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15535 (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
15536 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15537
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15538 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
15539 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
15540 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
15541 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
15542 @code{insert-rectangle} command to insert.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15543
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15544 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
15545 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
15546 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
15547 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
15548 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
15549 @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
15550
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15551 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15552 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15553 ;;; @r{First version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15554 (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
15555 "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
15556 (let ((insert-list nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15557 (number-of-top-blanks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15558 (- max-graph-height actual-height)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15559 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15560
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15561 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15562 ;; @r{Fill in asterisks.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15563 (while (> actual-height 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15564 (setq insert-list (cons "*" insert-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15565 (setq actual-height (1- actual-height)))
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{Fill in blanks.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15570 (while (> number-of-top-blanks 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15571 (setq insert-list (cons " " insert-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15572 (setq number-of-top-blanks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15573 (1- number-of-top-blanks)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15574 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15575
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15576 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15577 ;; @r{Return whole list.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15578 insert-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15579 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15580 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15581
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15582 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
15583 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
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 (column-of-graph 5 3)
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15590 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15591 returns
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15592
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15593 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15594 (" " " " "*" "*" "*")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15595 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15596
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15597 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
15598 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
15599 `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
15600 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
15601 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
15602 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
15603 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
15604 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
15605 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
15606 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
15607 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
15608 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
15609 those variables separately.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15610
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15611 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
15612 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
15613
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15614 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15615 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15616 (defvar graph-symbol "*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15617 "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
15618 @end group
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15621 (defvar graph-blank " "
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15622 "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
15623 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
15624 as graph-symbol.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15625 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15626 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15627
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15628 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15629 (For an explanation of @code{defvar}, see
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15630 @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
15631
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15632 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15633 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15634 ;;; @r{Second version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15635 (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
15636 "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
15637
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15638 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15639 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15640 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
15641 of the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15642 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
15643 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
15644 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15645
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15646 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15647 (let ((insert-list nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15648 (number-of-top-blanks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15649 (- max-graph-height actual-height)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15650 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15651
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15652 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15653 ;; @r{Fill in @code{graph-symbols}.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15654 (while (> actual-height 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15655 (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
15656 (setq actual-height (1- actual-height)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15657 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15658
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15659 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15660 ;; @r{Fill in @code{graph-blanks}.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15661 (while (> number-of-top-blanks 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15662 (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
15663 (setq number-of-top-blanks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15664 (1- number-of-top-blanks)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15665
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15666 ;; @r{Return whole list.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15667 insert-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15668 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15669 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15670
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15671 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
15672 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
15673 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
15674 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
15675 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
15676 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
15677 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
15678 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
15679 the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15680
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15681 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
15682 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
15683 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
15684 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
15685 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
15686 simple.
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 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
15689 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
15690 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
15691
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15692 @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
15693 @section The @code{graph-body-print} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15694 @findex graph-body-print
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 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
15697 @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
15698 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
15699 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
15700 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
15701 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
15702 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
15703
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15704 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
15705 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
15706
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15707 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
15708 version of this function:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15711 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15712 (defun graph-body-print (numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15713 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15714 (let ((height @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15715 @dots{}))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15716 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15717
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15718 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15719 (while numbers-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15720 @var{insert-columns-and-reposition-point}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15721 (setq numbers-list (cdr numbers-list)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15722 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15723 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15724
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15725 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15726 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
15727
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15728 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
15729 determine the height of the graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15730
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15731 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
15732 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
15733 (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
15734 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
15735
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15736 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
15737 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
15738 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
15739 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
15740 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
15741 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
15742 from which @code{insert-rectangle} is called.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15743
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15744 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
15745 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
15746 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
15747 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
15748 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
15749 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
15750 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
15751 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
15752 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
15753
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15754 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15755 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
15756
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15757 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15758 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15759 (defun graph-body-print (numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15760 "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
15761 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
15762
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15763 (let ((height (apply 'max numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15764 (symbol-width (length graph-blank))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15765 from-position)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15766 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15767
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 (while numbers-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15770 (setq from-position (point))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15771 (insert-rectangle
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15772 (column-of-graph height (car numbers-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15773 (goto-char from-position)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15774 (forward-char symbol-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15775 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15776 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15777 ;; @r{Draw graph column by column.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15778 (sit-for 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15779 (setq numbers-list (cdr numbers-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15780 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15781 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15782 ;; @r{Place point for X axis labels.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15783 (forward-line height)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15784 (insert "\n")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15785 ))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15786 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15787 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15788
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15789 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15790 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
15791 @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
15792 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
15793 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
15794 `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
15795 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
15796 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
15797 function exits.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15798
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15799 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
15800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15801 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15802 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15803 Install @code{graph-symbol}, @code{graph-blank},
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15804 @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
15805 @iftex
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
15806 @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
15807 @end iftex
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
15808 @ifinfo
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
15809 @ref{Columns of a graph},
f2ffeff1bf1e Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents: 41421
diff changeset
15810 @end ifinfo
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15811 and @code{graph-body-print}.
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15814 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15815 Copy the following expression:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15818 (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
15819 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15820
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15821 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15822 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
15823 want the graph to start.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15824
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15825 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15826 Type @kbd{M-:} (@code{eval-expression}).
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 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15829 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
15830 with @kbd{C-y} (@code{yank)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15831
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15832 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15833 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
15834 @end enumerate
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15837 Emacs will print a graph like this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15840 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15841 *
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 * ****
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15844 *** ****
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15845 ********* *
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 *************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15848 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15849 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15850
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15851 @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
15852 @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
15853 @findex recursive-graph-body-print
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15854
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15855 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
15856 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
15857 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
15858 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
15859 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
15860 the graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15861
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15862 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15863 The `wrapper' is uncomplicated:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15864
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15865 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15866 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15867 (defun recursive-graph-body-print (numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15868 "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
15869 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
15870 (let ((height (apply 'max numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15871 (symbol-width (length graph-blank))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15872 from-position)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15873 (recursive-graph-body-print-internal
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15874 numbers-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15875 height
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15876 symbol-width)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15877 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15878 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15879
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15880 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
15881 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
15882 `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
15883 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
15884 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
15885 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
15886 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
15887 `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
15888 version of the @code{numbers-list}.
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15891 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15892 (defun recursive-graph-body-print-internal
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15893 (numbers-list height symbol-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15894 "Print a bar graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15895 Used within recursive-graph-body-print function."
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
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15898 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15899 (if numbers-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15900 (progn
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15901 (setq from-position (point))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15902 (insert-rectangle
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15903 (column-of-graph height (car numbers-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15904 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15905 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15906 (goto-char from-position)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15907 (forward-char symbol-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15908 (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
15909 (recursive-graph-body-print-internal
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15910 (cdr numbers-list) height symbol-width))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15911 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15912 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15913
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15914 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15915 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
15916
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15917 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15918 (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
15919 @end smallexample
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15922 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
15923
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15924 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15925 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15926 *
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 **** *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15929 **** ***
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 ************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15932 *************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15933 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15934 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15935
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15936 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
15937 @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
15938
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15939 @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
15940 @section Need for Printed Axes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15941
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15942 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
15943 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
15944 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
15945
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15946 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
15947 @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
15948 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
15949 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
15950 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
15951
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15952 @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
15953 @section Exercise
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 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
15956
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15957 @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
15958 @chapter Your @file{.emacs} File
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15959 @cindex @file{.emacs} file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15960 @cindex Customizing your @file{.emacs} file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15961 @cindex Initialization file
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 ``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
15964 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
15965 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
15966 it to suit themselves.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15967
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15968 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
15969 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
15970
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15971 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15972 * Default Configuration::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15973 * 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
15974 * defcustom:: Emacs will write code for you.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15975 * 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
15976 * Text and Auto-fill:: Automatically wrap lines.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15977 * Mail Aliases:: Use abbreviations for email addresses.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15978 * 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
15979 * Keybindings:: Create some personal keybindings.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15980 * Keymaps:: More about key binding.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15981 * 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
15982 * Autoload:: Make functions available.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15983 * 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
15984 * 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
15985 * Miscellaneous::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15986 * 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
15987 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15988
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15989 @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
15990 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15991 @unnumberedsec Emacs' Default Configuration
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15992 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15993
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
15994 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
15995 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
15996 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
15997 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
15998 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
15999 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
16000 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
16001 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
16002 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
16003
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16004 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
16005 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
16006 customize Emacs: so it suits me.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16007
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16008 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
16009 @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
16010 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
16011 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
16012 @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
16013 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
16014 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
16015 naming conventions; the old format saves typing.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16016
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16017 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
16018 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
16019 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
16020 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
16021
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16022 (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
16023 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
16024 @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
16025
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16026 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
16027 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
16028 @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
16029 @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
16030 Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16031
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16032 @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
16033 @section Site-wide Initialization Files
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 @cindex @file{default.el} init file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16036 @cindex @file{site-init.el} init file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16037 @cindex @file{site-load.el} init file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16038 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
16039 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
16040 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
16041 everyone.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16042
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16043 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
16044 @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
16045 `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
16046 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
16047 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
16048 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
16049 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
16050 @file{INSTALL} file.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16051
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16052 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
16053 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
16054 @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
16055 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
16056 loaded @emph{after} your @file{.emacs} file.
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 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
16059 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
16060 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
16061 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
16062 (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
16063 @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
16064 Simple Extension}.)
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 @c Rewritten to avoid overfull hbox.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16067 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
16068 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
16069
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16070 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
16071 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
16072 Emacs distribution and are worth perusing.
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 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
16075 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
16076 initialization file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16077
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16078 @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
16079 @section Specifying Variables using @code{defcustom}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16080 @findex defcustom
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16081
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16082 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
16083 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
16084 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
16085 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
16086 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
16087 file.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16088
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16089 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
16090 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
16091 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
16092 job.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16093
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16094 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
16095 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
16096 @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
16097 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
16098 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
16099 documentation.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16100
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16101 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
16102 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
16103 arguments are optional.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16104
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16105 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
16106 Each keyword starts with the character @code{:}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16107
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16108 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16109 For example, the customizable user option variable
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16110 @code{text-mode-hook} looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16111
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16112 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16113 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16114 (defcustom text-mode-hook nil
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16115 "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
16116 :type 'hook
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16117 :options '(turn-on-auto-fill flyspell-mode)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16118 :group 'data)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16119 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16120 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16123 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
16124 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
16125
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16126 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
16127 @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
16128 a Customization buffer.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16129
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16130 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
16131 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
16132 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
16133 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
16134 @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
16135 user.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16136
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16137 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
16138 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
16139 find it.
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 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
16142 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
16143
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16144 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
16145
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16146 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
16147 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
16148
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16149 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16150 Using the customization command, you can type:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16151
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16152 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16153 M-x customize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16154 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16155
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16156 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16157 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
16158 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
16159 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
16160 button to
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 Save for Future Sessions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16164 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16165
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16166 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16167 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
16168 It will look like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16169
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16170 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16171 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16172 (custom-set-variables
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16173 ;; custom-set-variables was added by Custom --
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16174 ;; don't edit or cut/paste it!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16175 ;; 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
16176 '(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
16177 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16178 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16179
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16180 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16181 (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
16182 @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
16183
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16184 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
16185 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
16186 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
16187 inadvertently generate an error.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16188
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16189 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
16190 @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
16191 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
16192 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
16193 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
16194 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
16195
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16196 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
16197 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
16198 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
16199 @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
16200 @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
16201
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16202 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
16203 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
16204 with the @code{custom-set-@dots{}} functions.
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 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
16208 message that says
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16209
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16210 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16211 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
16212 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16213
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16214 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16215 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
16216
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16217 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16218 Save for Future Sessions
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16219 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16222 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
16223 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
16224 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
16225 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
16226 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
16227 forget, you may confuse yourself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16228
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16229 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
16230 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
16231 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
16232
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16233 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
16234 expressions myself.
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 @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
16237 @section Beginning a @file{.emacs} File
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16238 @cindex @file{.emacs} file, beginning of
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 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
16241 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
16242 @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
16243
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16244 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
16245 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
16246 definitions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16247
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16248 @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
16249 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
16250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16251 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
16252 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
16253
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16254 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
16255 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
16256 not.
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16259 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16260 ;;;; Bob's .emacs file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16261 ; Robert J. Chassell
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16262 ; 26 September 1985
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16263 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16264 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16265
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16266 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16267 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
16268 adding to it ever since.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16269
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16270 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16271 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16272 ; 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
16273 ; line beginning with four semicolons; and each
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16274 ; 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
16275 ; three semicolons.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16276 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16277 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16278
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16279 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16280 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
16281 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
16282 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
16283 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
16284 Manual}, for more about comments.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16285
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16286 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16287 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16288 ;;;; The Help Key
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16289 ; Control-h is the help key;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16290 ; 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
16291 ; 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
16292 ; For an explanation of the help facility,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16293 ; 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
16294 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16295 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16296
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16297 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16298 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
16299
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16300 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16301 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16302 ; 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
16303 ; 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
16304 ; 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
16305 ; control-h m.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16306 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16307 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16308
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16309 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16310 `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
16311 all you need to know.
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 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
16314 @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
16315 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
16316 remember to look here to remind myself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16317
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16318 @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
16319 @section Text and Auto Fill Mode
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16320
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16321 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
16322 Auto Fill mode.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16323
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16324 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16325 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16326 ;;; Text mode and Auto Fill mode
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16327 ; 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
16328 ; 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
16329 ; 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
16330
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16331 (setq default-major-mode 'text-mode)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16332 (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
16333 (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
16334 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16335 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16336
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16337 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
16338 besides remind a forgetful human!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16339
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16340 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
16341 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
16342 other mode, such as C mode.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16343
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16344 @cindex Per-buffer, local variables list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16345 @cindex Local variables list, per-buffer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16346 @cindex Automatic mode selection
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16347 @cindex Mode selection, automatic
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16348 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
16349 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
16350 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
16351 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
16352 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
16353 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
16354 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
16355 per-buffer, ``local variables list'', if any.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16356
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16357 @ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16358 @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
16359 Emacs Manual}.
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 @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
16362 Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16363 @end ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16364 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16365 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
16366 Files'' in @cite{The GNU Emacs Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16367 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16368
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16369 Now, back to the @file{.emacs} file.
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16372 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
16373
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16374 @cindex Text Mode turned on
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16375 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16376 (setq default-major-mode 'text-mode)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16377 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16378
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16379 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16380 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
16381
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16382 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
16383 @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
16384 @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
16385 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
16386 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
16387 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
16388 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
16389 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
16390 else in Emacs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16391
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16392 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16393 Here are the next two lines:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16394
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16395 @cindex Auto Fill mode turned on
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16396 @findex add-hook
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16397 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16398 (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
16399 (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
16400 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16401
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16402 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16403 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
16404 @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
16405 @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
16406 variable.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16407
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16408 @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
16409 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
16410 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
16411 are in Text mode.
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 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
16414 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
16415 turns on Auto Fill mode.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16416
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16417 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
16418 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
16419 variables tell Emacs otherwise.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16420
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16421 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
16422 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
16423 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
16424 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
16425 @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
16426 the @samp{t} of @samp{it's}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16427
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16428 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
16429 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
16430 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
16431 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
16432 within them.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16433
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16434 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
16435 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
16436 @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
16437 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
16438 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
16439
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16440 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16441 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
16442 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
16443
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16444 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16445 (setq colon-double-space t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16446 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16447
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16448 @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
16449 @section Mail Aliases
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16450
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16451 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
16452 reminders.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16453
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16454 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16455 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16456 ;;; Mail mode
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16457 ; 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
16458 ; To enter RMAIL (for reading mail),
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16459 ; type `M-x rmail'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16460
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16461 (setq mail-aliases t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16462 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16463 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16464
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16465 @cindex Mail aliases
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16466 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16467 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
16468 @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
16469 says, in effect, ``Yes, use mail aliases.''
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 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
16472 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
16473 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
16474
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16475 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16476 alias geo george@@foobar.wiz.edu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16477 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16478
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16479 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16480 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
16481 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
16482
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16483 @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
16484 @section Indent Tabs Mode
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16485 @cindex Tabs, preventing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16486 @findex indent-tabs-mode
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16487
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16488 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
16489 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
16490 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
16491 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
16492 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
16493
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16494 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16495 The following turns off Indent Tabs mode:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16496
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16497 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16498 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16499 ;;; Prevent Extraneous Tabs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16500 (setq-default indent-tabs-mode nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16501 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16502 @end smallexample
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 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
16505 @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
16506 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
16507 values for the variable.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16508
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16509 @ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16510 @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
16511
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16512 @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
16513 Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16514 @end ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16515 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16516 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
16517 Files'' in @cite{The GNU Emacs Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16518 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16519
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16520 @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
16521 @section Some Keybindings
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16522
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16523 Now for some personal keybindings:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16524
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16525 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16526 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16527 ;;; Compare windows
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16528 (global-set-key "\C-cw" 'compare-windows)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16529 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16530 @end smallexample
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 @findex compare-windows
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16533 @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
16534 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
16535 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
16536 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
16537
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16538 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
16539
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16540 @cindex Setting a key globally
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16541 @cindex Global set key
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16542 @cindex Key setting globally
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16543 @findex global-set-key
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16544 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
16545 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
16546 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
16547 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
16548 `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
16549 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
16550 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
16551 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
16552 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
16553 Manual}, for details.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16554
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16555 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
16556 @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
16557 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
16558
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16559 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
16560 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
16561 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
16562 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
16563 adapt what is there.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16564
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16565 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
16566 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
16567 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
16568 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
16569 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
16570 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
16571 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
16572 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
16573 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
16574
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16575 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16576 Here is another keybinding, with a comment:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16579 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16580 ;;; Keybinding for `occur'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16581 ; 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
16582 (global-set-key "\C-co" 'occur)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16583 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16584 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16585
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16586 @findex occur
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16587 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
16588 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
16589 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
16590 to jump to occurrences.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16591
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16592 @findex global-unset-key
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16593 @cindex Unbinding key
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16594 @cindex Key unbinding
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16595 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16596 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
16597 work:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16598
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16599 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16600 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16601 ;;; Unbind `C-x f'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16602 (global-unset-key "\C-xf")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16603 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16604 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16605
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16606 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
16607 @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
16608 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
16609 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
16610 default width, I simply unbound the key.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16611
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16612 @findex list-buffers, @r{rebound}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16613 @findex buffer-menu, @r{bound to key}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16614 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16615 The following rebinds an existing key:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16616
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16617 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16618 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16619 ;;; 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
16620 (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
16621 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16622 @end smallexample
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 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
16625 @code{list-buffers} command. This command lists
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16626 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
16627 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
16628 window, I prefer the @code{buffer-menu}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16629 command, which not only lists the buffers,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16630 but moves point into that window.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16631
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16632 @node Keymaps, Loading Files, Keybindings, Emacs Initialization
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16633 @section Keymaps
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16634 @cindex Keymaps
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16635 @cindex Rebinding keys
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16636
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16637 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
16638 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
16639 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
16640 @code{current-global-map}.
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 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
16643 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
16644 all buffers.
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 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
16647 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
16648 function @code{buffer-menu}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16649
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16650 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16651 (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
16652 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16653
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16654 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
16655 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
16656 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
16657 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
16658 to @kbd{C-c C-c g}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16659
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16660 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16661 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16662 (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
16663 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16664 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16665
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16666 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16667 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
16668 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
16669 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
16670 @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
16671 (@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
16672 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
16673 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
16674
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16675 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16676 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
16677
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16678 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16679 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16680 (defun texinfo-insert-@@group ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16681 "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
16682 (interactive)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16683 (beginning-of-line)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16684 (insert "@@group\n"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16685 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16686 @end smallexample
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 (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
16689 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
16690 with other Texinfo mode key bindings.)
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 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
16693 @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
16694 @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
16695
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16696 @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
16697 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
16698 Reference Manual}, for more information about keymaps.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16699
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16700 @node Loading Files, Autoload, Keymaps, Emacs Initialization
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16701 @section Loading Files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16702 @cindex Loading files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16703 @c findex load
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16704
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16705 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
16706 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
16707 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
16708 of the standard GNU Emacs.
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 (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
16711 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
16712 separately and no one has changed that.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16713
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16714 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
16715 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
16716 For example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16717
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16718 @c (auto-compression-mode t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16719
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16720 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16721 (load "~/emacs/slowsplit")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16722 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16723
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16724 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
16725 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
16726 @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
16727 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
16728 1989.
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 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
16731 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
16732 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
16733 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
16734 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
16735 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
16736 window.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16737
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16738 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16739 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
16740 @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
16741 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
16742
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16743 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16744 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16745 (global-unset-key "\C-x2")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16746 (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
16747 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16748 @end smallexample
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 @vindex load-path
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16751 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
16752 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
16753 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
16754 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
16755 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
16756 when Emacs is built.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16757
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16758 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16759 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
16760 existing load path:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16761
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16762 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16763 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16764 ;;; Emacs Load Path
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16765 (setq load-path (cons "~/emacs" load-path))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16766 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16767 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16768
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16769 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
16770 @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
16771
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16772 @findex load-library
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16773 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16774 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16775 (defun load-library (library)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16776 "Load the library named LIBRARY.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16777 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
16778 (interactive "sLoad library: ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16779 (load library))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16780 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16781 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16782
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16783 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
16784 `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
16785 @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
16786
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16787 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
16788 @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
16789 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
16790 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
16791
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16792 @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
16793 @section Autoloading
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16794 @findex autoload
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 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
16797 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
16798 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
16799 is called @dfn{autoloading}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16801 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
16802 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
16803
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16804 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
16805 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
16806 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
16807
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16808 Rarely used functions are frequently autoloaded. The
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16809 @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
16810 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
16811 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
16812 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
16813 @file{.emacs} file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16814
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16815 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
16816 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
16817 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
16818 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
16819 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
16820 file for more about dumping.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16821
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16822 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
16823 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
16824 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
16825 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
16826 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
16827 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
16828 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
16829 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
16830 function (the default is a function).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16831
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16832 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16833 Here is a typical example:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16834
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16835 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16836 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16837 (autoload 'html-helper-mode
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16838 "html-helper-mode" "Edit HTML documents" t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16839 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16840 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16841
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16842 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16843 (@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
16844 is a standard part of the distribution).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16845
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16846 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16847 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
16848 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
16849 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
16850 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
16851 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
16852 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
16853 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
16854 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
16855 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
16856 documentation is not available.)
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 @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
16859 Manual}, for more information.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16860
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16861 @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
16862 @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
16863 @findex line-to-top-of-window
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16864 @cindex Simple extension in @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 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
16867 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
16868 to read.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16869
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16870 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
16871 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
16872 @file{.emacs} file.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16873
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16874 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16875 Here is the definition:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16876
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16877 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16878 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16879 ;;; Line to top of window;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16880 ;;; 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
16881 (defun line-to-top-of-window ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16882 "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
16883 (interactive)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16884 (recenter 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16885 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16886 @end smallexample
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16889 Now for the keybinding.
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 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
16892 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
16893 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
16894 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
16895
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16896 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
16897 this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16898
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16899 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16900 (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
16901 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16902
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16903 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
16904 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
16905
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16906 @cindex Conditional 'twixt two versions of Emacs
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16907 @cindex Version of Emacs, choosing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16908 @cindex Emacs version, choosing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16909 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
16910 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
16911 the following conditional:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16912
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16913 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16914 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16915 (cond
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16916 ((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
16917 ;; evaluate version 20 code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16918 ( @dots{} ))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16919 ((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
16920 ;; evaluate version 21 code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16921 ( @dots{} )))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16922 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16923 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16924
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16925 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
16926 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
16927 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
16928 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
16929 @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
16930
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16931 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16932 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
16933 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16934 }:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16935
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16936 @smallexample
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 (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
16939 (progn
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16940 (blink-cursor-mode 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16941 ;; 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
16942 ;; at the end of the buffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16943 (setq next-line-add-newlines t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16944 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16945 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16946 ;; Turn on image viewing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16947 (auto-image-file-mode t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16948 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16949 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16950 ;; 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
16951 ;; (Use numeric argument to turn on)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16952 (menu-bar-mode 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16953 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16954 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16955 ;; 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
16956 ;; (Use numeric argument to turn on)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16957 (tool-bar-mode nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16958 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16959 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16960 ;; Turn off tooltip mode for tool bar
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16961 ;; (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
16962 ;; (Use numeric argument to turn on)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16963 (tooltip-mode nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16964 ;; 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
16965 (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
16966 ))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16967 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16968 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16969
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16970 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16971 (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
16972 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
16973 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
16974 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
16975 @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
16976 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
16977 @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
16978
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16979 @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
16980 @section X11 Colors
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16981
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16982 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
16983 system.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16984
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16985 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
16986
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16987 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16988 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
16989 file that set values:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16992 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16993 ;; Set cursor color
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16994 (set-cursor-color "white")
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 ;; Set mouse color
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16997 (set-mouse-color "white")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16998
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
16999 ;; Set foreground and background
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17000 (set-foreground-color "white")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17001 (set-background-color "darkblue")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17002 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17003
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17004 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17005 ;;; Set highlighting colors for isearch and drag
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17006 (set-face-foreground 'highlight "white")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17007 (set-face-background 'highlight "blue")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17008 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17009
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17010 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17011 (set-face-foreground 'region "cyan")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17012 (set-face-background 'region "blue")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17013 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17014
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17015 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17016 (set-face-foreground 'secondary-selection "skyblue")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17017 (set-face-background 'secondary-selection "darkblue")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17018 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17019
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17020 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17021 ;; Set calendar highlighting colors
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17022 (setq calendar-load-hook
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17023 '(lambda ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17024 (set-face-foreground 'diary-face "skyblue")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17025 (set-face-background 'holiday-face "slate blue")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17026 (set-face-foreground 'holiday-face "white")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17027 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17028 @end smallexample
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 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
17031 the screen flicker.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17032
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17033 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
17034 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
17035 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
17036 @file{~/.Xresources} file like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17037
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17038 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17039 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17040 Emacs*foreground: white
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17041 Emacs*background: darkblue
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17042 Emacs*cursorColor: white
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17043 Emacs*pointerColor: white
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17044 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17045 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17046
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17047 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
17048 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
17049 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
17050 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
17051 image rather than a plain color.}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17052
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17053 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17054 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17055 # I use TWM for window manager.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17056 xsetroot -solid Navy -fg white &
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17057 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17058 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17059
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17060 @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
17061 @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
17062
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17063 Here are a few miscellaneous settings:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17064 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17065
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17066 @itemize @minus
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17067 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17068 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
17069 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17070 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17071 ; Cursor shapes are defined in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17072 ; `/usr/include/X11/cursorfont.h';
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17073 ; 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
17074 ; 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
17075 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17076
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 (let ((mpointer (x-get-resource "*mpointer"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17079 "*emacs*mpointer")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17080 ;; 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
17081 ;; then set it, otherwise leave as is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17082 (if (eq mpointer nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17083 (setq mpointer "132")) ; top_left_arrow
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17084 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17085 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17086 (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
17087 (set-mouse-color "white"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17088 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17089 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17090 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17091
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17092 @node Mode Line, , Miscellaneous, Emacs Initialization
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17093 @section A Modified Mode Line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17094 @vindex default-mode-line-format
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17095 @cindex Mode line format
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17096
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17097 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
17098
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17099 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
17100 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
17101
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17102 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
17103
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17104 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17105 -:-- 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
17106 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17107
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17108 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
17109 @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
17110 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
17111
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17112 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17113 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
17114
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17115 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17116 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17117 ;; 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
17118 ;; 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
17119 (setq default-mode-line-format
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17120 (quote
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17121 (#("-" 0 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17122 (help-echo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17123 "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
17124 mode-line-mule-info
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17125 mode-line-modified
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17126 mode-line-frame-identification
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17127 " "
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17128 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17129 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17130 mode-line-buffer-identification
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17131 " "
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17132 (:eval (substring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17133 (system-name) 0 (string-match "\\..+" (system-name))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17134 ":"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17135 default-directory
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17136 #(" " 0 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17137 (help-echo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17138 "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
17139 (line-number-mode " Line %l ")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17140 global-mode-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17141 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17142 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17143 #(" %[(" 0 6
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17144 (help-echo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17145 "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
17146 (:eval (mode-line-mode-name))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17147 mode-line-process
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17148 minor-mode-alist
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17149 #("%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
17150 ")%] "
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17151 (-3 . "%P")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17152 ;; "-%-"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17153 )))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17154 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17155 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17156
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17157 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17158 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
17159 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
17160 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
17161 it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17162
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17163 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
17164 @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
17165 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
17166 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
17167 have not discussed.
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 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
17170 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
17171 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
17172 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
17173 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
17174 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
17175 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
17176
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17177 @need 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17178 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
17179
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17180 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17181 #("-" 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
17182 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17183
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17184 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17185 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
17186 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
17187 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
17188 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
17189 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
17190 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
17191 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
17192 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
17193 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
17194 string format can be repeated.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17195
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17196 @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
17197 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
17198 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
17199 information.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17201 @code{mode-line-buffer-identification}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17202 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
17203 beginning @code{(#("%12b" 0 4 @dots{}}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17204 The @code{#(} begins the list.
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 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
17207 @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
17208 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
17209 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
17210 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
17211 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
17212 window.)
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 @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
17215 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
17216 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
17217 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
17218 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
17219 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
17220 length is the name of the machine.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17221
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17222 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17223 This is the expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17224
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17225 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17226 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17227 (:eval (substring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17228 (system-name) 0 (string-match "\\..+" (system-name))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17229 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17230 @end smallexample
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 @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
17233 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
17234 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
17235 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
17236 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
17237 @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
17238 out the line.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17239
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17240 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
17241 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
17242 keys than a default Emacs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17243
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17244 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
17245 Emacs, with no customization, type:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17246
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17247 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17248 emacs -q
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17249 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17251 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17252 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
17253 @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
17254 more.
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 @node Debugging, Conclusion, Emacs Initialization, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17257 @chapter Debugging
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17258 @cindex debugging
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 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
17261 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
17262 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
17263
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17264 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
17265 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
17266 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
17267
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17268 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17269 * 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
17270 * 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
17271 * 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
17272 * 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
17273 * Debugging Exercises::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17274 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17275
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17276 @node debug, debug-on-entry, Debugging, Debugging
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17277 @section @code{debug}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17278 @findex debug
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17279
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17280 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
17281 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
17282 @code{triangle} function discussed earlier. @xref{Decrementing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17283 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
17284 @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
17285
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17286 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
17287 @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
17288
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17289 @findex triangle-bugged
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17290 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17291 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17292 (defun triangle-bugged (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17293 "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
17294 (let ((total 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17295 (while (> number 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17296 (setq total (+ total number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17297 (setq number (1= number))) ; @r{Error here.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17298 total))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17299 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17300 @end smallexample
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 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
17303 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
17304 echo area.
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17307 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
17308 argument of 4:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17311 (triangle-bugged 4)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17312 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17313
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17314 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17315 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
17316 @file{*Backtrace*} buffer that says:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17317
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17318 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17319 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17320 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17321 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17322 Debugger entered--Lisp error: (void-function 1=)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17323 (1= number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17324 (setq number (1= number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17325 (while (> number 0) (setq total (+ total number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17326 (setq number (1= number)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17327 (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
17328 (setq number ...)) total)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17329 triangle-bugged(4)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17330 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17331 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17332 eval((triangle-bugged 4))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17333 eval-last-sexp-1(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17334 eval-last-sexp(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17335 call-interactively(eval-last-sexp)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17336 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17337 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17338 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17339
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17340 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17341 (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
17342 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
17343 the @file{*Backtrace*} buffer.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17344
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17345 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
17346 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
17347 function @code{1=} is `void'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17348
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17349 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17350 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
17351
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17352 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17353 Symbol's function definition is void:@: 1=
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17354 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17355
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17356 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17357 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
17358 version 21.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17359
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17360 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
17361 You can read the complete backtrace.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17362
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17363 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
17364 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
17365 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
17366
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17367 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
17368 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
17369 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
17370 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
17371 what the Lisp interpreter evaluated next.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17372
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17373 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17374 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
17375
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17376 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17377 (setq number (1= number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17378 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17379
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17380 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17381 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
17382 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
17383 top:
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 (1= number)
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17390 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17391 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
17392
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17393 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17394 Debugger entered--Lisp error: (void-function 1=)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17395 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17398 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
17399 then run your test again.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17400
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17401 @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
17402 @section @code{debug-on-entry}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17403 @findex debug-on-entry
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17404
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17405 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
17406 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
17407 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
17408 manually.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17409
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17410 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
17411 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
17412 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
17413
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17414 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
17415 @code{debug-on-entry}.
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 Type:
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 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
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17426 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17427 Now, evaluate the following:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17428
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17429 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17430 (triangle-bugged 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17431 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17432
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17433 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17434 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
17435 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
17436 function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17437
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17438 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17439 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17440 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17441 Debugger entered--entering a function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17442 * triangle-bugged(5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17443 eval((triangle-bugged 5))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17444 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17445 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17446 eval-last-sexp-1(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17447 eval-last-sexp(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17448 call-interactively(eval-last-sexp)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17449 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17450 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17451 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17452
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17453 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
17454 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
17455 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17456
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17457 @smallexample
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 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17460 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
17461 * (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
17462 (setq number ...)) total)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17463 * triangle-bugged(5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17464 eval((triangle-bugged 5))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17465 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17466 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17467 eval-last-sexp-1(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17468 eval-last-sexp(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17469 call-interactively(eval-last-sexp)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17470 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17471 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17472 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17475 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
17476 @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
17477 definition.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17478
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17479 @need 1750
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17480 Eventually, the buffer will look like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17481
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17482 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17483 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17484 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17485 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
17486 * (setq number (1= number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17487 * (while (> number 0) (setq total (+ total number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17488 (setq number (1= number)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17489 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17490 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17491 * (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
17492 (setq number ...)) total)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17493 * triangle-bugged(5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17494 eval((triangle-bugged 5))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17495 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17496 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17497 eval-last-sexp-1(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17498 eval-last-sexp(nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17499 call-interactively(eval-last-sexp)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17500 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17501 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17502 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17503
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17504 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17505 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
17506 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
17507 like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17508
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17509 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17510 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17511 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17512 Debugger entered--Lisp error: (void-function 1=)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17513 * (1= number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17514 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17515 ---------- Buffer: *Backtrace* ----------
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17516 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17517 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17518
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17519 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
17520
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17521 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
17522 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
17523
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17524 @findex cancel-debug-on-entry
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17525 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
17526 @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
17527
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17528 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17529 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
17530 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17531
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17532 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17533 (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
17534
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17535 @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
17536 @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
17537
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17538 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
17539 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
17540
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17541 @findex debug-on-quit
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17542 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
17543 (@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
17544 @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
17545
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17546 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17547 @cindex @code{(debug)} in code
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17548 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
17549 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
17550
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17551 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17552 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17553 (defun triangle-bugged (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17554 "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
17555 (let ((total 0))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17556 (while (> number 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17557 (setq total (+ total number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17558 (debug) ; @r{Start debugger.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17559 (setq number (1= number))) ; @r{Error here.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17560 total))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17561 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17562 @end smallexample
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 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
17565 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
17566
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17567 @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
17568 @section The @code{edebug} Source Level Debugger
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17569 @cindex Source level debugger
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17570 @findex edebug
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17571
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17572 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
17573 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
17574 shows which line you are currently executing.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17575
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17576 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
17577 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
17578
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17579 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
17580 Lisp Reference Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17581
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17582 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
17583 @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
17584 for a review of it.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17585
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17586 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17587 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17588 (defun triangle-recursively-bugged (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17589 "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
17590 Uses recursion."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17591 (if (= number 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17592 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17593 (+ number
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17594 (triangle-recursively-bugged
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17595 (1= number))))) ; @r{Error here.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17596 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17597 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17600 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
17601 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
17602 (@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
17603 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
17604 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
17605 Interactive mode.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17606
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17607 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17608 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
17609 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
17610 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
17611
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17612 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17613 M-x edebug-defun RET
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17614 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17615
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17616 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17617 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
17618 already loaded, and properly instrument the function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17619
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17620 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
17621 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
17622
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17623 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17624 (triangle-recursively-bugged 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17625 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17626
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17627 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17628 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
17629 @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
17630 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
17631 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
17632 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
17633 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
17634 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
17635
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17636 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17637 =>@point{}(if (= number 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17638 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17639
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17640 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17641 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17642 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
17643 @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
17644 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17645 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17646 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
17647 (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
17648 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17649
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17650 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
17651 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
17652
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17653 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17654 =>(if @point{}(= number 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17655 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17656
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17657 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17658 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
17659 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
17660 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
17661 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
17662
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17663 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17664 Result: 3 = C-c
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17665 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17666
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17667 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17668 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
17669 `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
17670
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17671 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
17672 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
17673
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17674 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17675 => @point{}(1= number))))) ; @r{Error here.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17676 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17677
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17678 @need 1250
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 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
17681 that says:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17682
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17683 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17684 Symbol's function definition is void:@: 1=
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17685 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17686
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17687 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17688 This is the bug.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17689
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17690 Press @kbd{q} to quit Edebug.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17691
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17692 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
17693 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
17694 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
17695 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
17696
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17697 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
17698 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
17699 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
17700 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
17701 times a function is called, and more.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17702
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17703 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
17704 Lisp Reference Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17705
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17706 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17707 @node Debugging Exercises, , edebug, Debugging
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17708 @section Debugging Exercises
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17709
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17710 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17711 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17712 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
17713 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
17714 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
17715 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
17716 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
17717 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
17718 Manual}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17719
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17720 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17721 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
17722 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
17723 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
17724 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
17725 completes without problems.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17726
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17727 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17728 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
17729 (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
17730 @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
17731 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
17732
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17733 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17734 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
17735 (@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
17736 @code{count-words-region} is working.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17737
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17738 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17739 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
17740 @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
17741
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17742 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17743 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
17744 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
17745 @code{edebug-Trace-fast-mode}.
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 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17748 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
17749 stopping point.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17750 @end itemize
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 @node Conclusion, the-the, Debugging, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17753 @chapter Conclusion
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 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
17756 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
17757 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
17758 simple customizations and extensions to Emacs.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17759
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17760 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
17761 teach yourself.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17762
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17763 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
17764 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
17765 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
17766
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17767 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
17768 and in
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17769 @ifnotinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17770 @cite{The GNU Emacs Lisp Reference Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17771 @end ifnotinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17772 @ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17773 @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
17774 Emacs Lisp Reference Manual}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17775 @end ifinfo
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17776
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17777 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
17778 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
17779 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
17780
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17781 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
17782 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
17783 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
17784 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
17785 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
17786 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
17787
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17788 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
17789 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
17790 that takes you to sources.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17791
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17792 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
17793 @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
17794 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
17795 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
17796 function, for example, looks complicated.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17797
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17798 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
17799 @code{forward-sentence} function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17800 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17801 (@xref{forward-sentence}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17802 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17803 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17804 (@xref{forward-sentence, , @code{forward-sentence}}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17805 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17806 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
17807 @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
17808 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
17809 function contains 27 words and symbols.
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 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
17812 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
17813 @code{current-column} and @samp{?\n}.
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 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
17816 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
17817 @ref{Review, , Review}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17818
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17819 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
17820 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
17821 function. This gives you the function documentation.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17822
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17823 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
17824 @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
17825 @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
17826 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
17827 @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
17828
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17829 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
17830 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
17831 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
17832 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
17833 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
17834 (@code{find-tag}).
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17835
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17836 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
17837 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
17838 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
17839
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17840 (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
17841 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
17842 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
17843 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
17844 properly set up.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17845
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17846 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
17847 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
17848 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
17849 (@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
17850 @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
17851 manual.
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 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
17854 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
17855 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
17856 @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
17857 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
17858 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
17859 for the newline character.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17860
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17861 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
17862 @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
17863 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
17864 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
17865 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
17866 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
17867 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
17868 (@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
17869 Reference Manual}, for more about building.)
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 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
17872 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
17873 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
17874 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
17875 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
17876 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
17877 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
17878
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17879 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
17880 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
17881 beginning.
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 @c ================ Appendix ================
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17884
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17885 @node the-the, Kill Ring, Conclusion, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17886 @appendix The @code{the-the} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17887 @findex the-the
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17888 @cindex Duplicated words function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17889 @cindex Words, duplicated
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17890
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17891 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
17892 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
17893 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
17894 detecting duplicated words, @code{the-the}.
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17897 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
17898 search for duplicates:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17899
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17900 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17901 \\(\\w+[ \t\n]+\\)\\1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17902 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17903
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17904 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17905 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
17906 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
17907 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
17908 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
17909 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
17910 @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
17911 @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
17912 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
17913 The GNU Emacs Lisp Reference Manual}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17914
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17915 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
17916 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
17917 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
17918
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17919 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
17920 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
17921 @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
17922 @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
17923
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17924 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17925 \\(\\(\\w+\\)\\W*\\)\\1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17926 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17929 Again, not useful.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17930
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17931 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
17932 @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
17933 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
17934 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
17935
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17936 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17937 \\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17938 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17939
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17940 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
17941 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
17942
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17943 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
17944 @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
17945
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17946 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17947 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17948 (defun the-the ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17949 "Search forward for for a duplicated word."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17950 (interactive)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17951 (message "Searching for for duplicated words ...")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17952 (push-mark)
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17955 ;; This regexp is not perfect
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17956 ;; but is fairly good over all:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17957 (if (re-search-forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17958 "\\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
17959 (message "Found duplicated word.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17960 (message "End of buffer")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17961 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17962
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17963 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17964 ;; Bind `the-the' to C-c \
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17965 (global-set-key "\C-c\\" 'the-the)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17966 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17967 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17968
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17969 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17970 Here is test text:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17971
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17972 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17973 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17974 one two two three four five
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17975 five six seven
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17976 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17977 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17978
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17979 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
17980 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
17981
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17982 @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
17983 @appendix Handling the Kill Ring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17984 @cindex Kill ring handling
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17985 @cindex Handling the kill ring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17986 @cindex Ring, making a list like a
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17987
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17988 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
17989 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
17990 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
17991 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
17992 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
17993 commands.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17994
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17995 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17996 * 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
17997 * 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
17998 * yank-pop:: Insert first element pointed to.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
17999 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18001 @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
18002 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18003 @appendixsec The @code{rotate-yank-pointer} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18004 @findex 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 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
18007 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
18008 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
18009 element to point to the third element.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18010
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18011 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18012 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
18013
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18014 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18015 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18016 (defun rotate-yank-pointer (arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18017 "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
18018 (interactive "p")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18019 (let ((length (length kill-ring)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18020 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18021 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18022 (if (zerop length)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18023 ;; @r{then-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18024 (error "Kill ring is empty")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18025 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18026 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18027 ;; @r{else-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18028 (setq kill-ring-yank-pointer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18029 (nthcdr (% (+ arg
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18030 (- length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18031 (length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18032 kill-ring-yank-pointer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18033 length)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18034 kill-ring)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18035 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18036 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18037
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18038 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18039 * Understanding rotate-yk-ptr::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18040 * 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
18041 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18042
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18043 @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
18044 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18045 @unnumberedsubsec @code{rotate-yank-pointer} in Outline
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18046 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18047
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18048 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
18049 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
18050 it in skeletal form:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18051
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18052 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18053 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18054 (defun rotate-yank-pointer (arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18055 "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
18056 (interactive "p")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18057 (let @var{varlist}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18058 @var{body}@dots{})
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18059 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18060 @end smallexample
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 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
18063 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
18064 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
18065 function as a number.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18066
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18067 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
18068 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
18069
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18070 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
18071 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
18072 @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
18073 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
18074 @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
18075 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
18076 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
18077 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
18078 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
18079 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
18080
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18081 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
18082 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
18083 kill ring.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18084
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18085 @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
18086 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18087 @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
18088
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18089 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
18090 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
18091
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18092 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
18093 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
18094 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
18095 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
18096 work of the function is done.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18097
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18098 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
18099
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18100 @findex zerop
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18101 @findex error
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18102 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18103 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18104 (if (zerop length) ; @r{if-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18105 (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
18106 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18107 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18108 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18109
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18110 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18111 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
18112 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
18113 @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
18114 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
18115 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
18116 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
18117 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
18118 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
18119 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
18120 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
18121 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
18122
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18123 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18124 * 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
18125 * 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
18126 * Remainder Function:: The remainder, @code{%}, function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18127 * 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
18128 * 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
18129 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18130
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18131 @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
18132 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18133 @unnumberedsubsubsec Digression about the word `error'
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18134 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18135
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18136 (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
18137 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
18138 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
18139 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
18140 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
18141 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
18142 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
18143 exploration.
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 (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
18146 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
18147 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
18148 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
18149 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
18150 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
18151 `cancel' would have a clearer connotation.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18152
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18153 @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
18154 @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
18155
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18156 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
18157 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
18158 in it. The code looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18159
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18160 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18161 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18162 (setq kill-ring-yank-pointer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18163 (nthcdr (% (+ arg
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18164 (- length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18165 (length kill-ring-yank-pointer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18166 length)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18167 kill-ring)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18168 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18169 @end smallexample
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 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
18172 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
18173 @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
18174 (@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
18175
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18176 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
18177 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
18178
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18179 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
18180 @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
18181 @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
18182 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
18183 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
18184 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
18185 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
18186 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
18187 elements.)
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 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
18190 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
18191 @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
18192 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
18193 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
18194 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
18195 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
18196
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18197 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18198 That is, under these circumstances,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18199
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18200 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18201 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18202 (setq kill-ring-yank-pointer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18203 ("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
18204
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18205 (setq kill-ring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18206 ("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
18207 @end group
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 800
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 the code should do 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 (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
18216 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18217
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18218 @need 1000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18219 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18220 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
18221
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18222 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18223 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18224 kill-ring-yank-pointer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18225 @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
18226 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18227 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18228
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18229 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
18230 the job.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18231
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18232 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
18233 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
18234 @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
18235
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18236 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18237 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
18238
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18239 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18240 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18241 (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
18242
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18243 (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
18244 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18245 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18246
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18247 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
18248 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
18249 lots of arithmetic inside of it:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18251 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18252 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18253 (% (+ arg
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18254 (- length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18255 (length kill-ring-yank-pointer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18256 length)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18257 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18258 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18259
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18260 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
18261 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
18262
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18263 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
18264 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
18265 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
18266 @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
18267 list.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18268
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18269 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18270 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
18271
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18272 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18273 (- length (length kill-ring-yank-pointer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18274 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18275
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18276 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18277 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
18278 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
18279 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
18280 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
18281 @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
18282 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
18283 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
18284 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
18285
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18286 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
18287 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
18288 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
18289
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18290 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
18291 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
18292 @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
18293 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
18294 @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
18295
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18296 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
18297 @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
18298 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
18299 @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
18300 Consequently, the value of
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 (- 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 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
18308 that the value of the whole expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18309
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18310 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18311 (+ arg (- length (length kill-ring-yank-pointer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18312 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18313
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18314 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18315 will be 1.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18316
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18317 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
18318 the expression
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18319
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18320 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18321 (% 1 length)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18322 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18323
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18324 @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
18325 @unnumberedsubsubsec The @code{%} remainder function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18326
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18327 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
18328 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
18329 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
18330 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
18331 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
18332 remainder of 1.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18333
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18334 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
18335 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
18336 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
18337 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
18338 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
18339 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
18340 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
18341 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
18342
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18343 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18344 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18345 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
18346
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18347 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18348 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
18349
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18350 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18351 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
18352
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18353 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18354 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
18355
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18356 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18357 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
18358
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18359 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18360 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
18361 @end itemize
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18364 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18365 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
18366
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18367 @itemize @bullet
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18368 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18369 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
18370
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18371 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18372 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
18373
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18374 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18375 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
18376 @end itemize
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18377
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18378 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18379 and so on.
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18382 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
18383 evaluating
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18386 (% 1 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18387 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18388
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18389 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18390 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
18391 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
18392
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18393 @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
18394 @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
18395
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18396 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
18397 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
18398 @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
18399
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18400 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18401 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18402 (- length (length kill-ring-yank-pointer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18403 @result{} 0
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18404 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18405 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18406
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18407 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18408 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18409 therefore,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18410
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18411 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18412 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18413 (+ arg (- length (length kill-ring-yank-pointer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18414 @result{} 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18415 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18416 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18417
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18418 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18419 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18420 and consequently:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18423 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18424 (% (+ arg (- length (length kill-ring-yank-pointer)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18425 length)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18426 @result{} 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18427 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18428 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18431 regardless of the value of @code{length}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18432
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18433 @need 1250
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 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
18436 simplifies to:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18437
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18438 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18439 (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
18440 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18441
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18442 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18443 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
18444 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
18445 @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
18446
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18447 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
18448 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
18449 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
18450
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18451 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
18452 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
18453 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
18454 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
18455 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
18456 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
18457 @code{rotate-yank-pointer} is 1.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18458
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18459 @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
18460 @unnumberedsubsubsec Pointing to the last element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18461
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18462 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
18463 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
18464 @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
18465 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
18466 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
18467 the kill ring instead.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18468
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18469 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
18470 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
18471 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
18472 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
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 (% (+ 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
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18479 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
18480 looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18481
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18482 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18483 (% (+ 1 (- 5 1)) 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18484 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18485
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18486 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18487 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
18488 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
18489 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
18490 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
18491
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18492 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18493 (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
18494 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18495
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18496 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18497 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
18498 of the kill ring.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18499
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18500 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
18501 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
18502 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
18503 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
18504 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
18505 an entity with no end?)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18506
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18507 @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
18508 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18509 @appendixsec @code{yank}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18510 @findex yank
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18511
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18512 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
18513 @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
18514 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
18515
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18516 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18517 The code looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18518
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18519 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18520 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18521 (defun yank (&optional arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18522 "Reinsert the last stretch of killed text.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18523 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
18524 recently killed OR yanked.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18525 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
18526 (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
18527 most recently killed stretch of killed text.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18528 See also the command \\[yank-pop]."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18529 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18530 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18531
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18532 (interactive "*P")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18533 (rotate-yank-pointer (if (listp arg) 0
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18534 (if (eq arg '-) -1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18535 (1- arg))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18536 (push-mark (point))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18537 (insert (car kill-ring-yank-pointer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18538 (if (consp arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18539 (exchange-point-and-mark)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18540 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18541 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18542
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18543 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
18544 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
18545 (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
18546 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
18547 @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
18548 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
18549 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
18550 @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
18551 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
18552
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18553 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18554 * 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
18555 * 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
18556 @end menu
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 @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
18559 @unnumberedsubsubsec Passing the argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18560
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18561 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
18562 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
18563 @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
18564 looks at first sight.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18565
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18566 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
18567 @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
18568 argument passed to @code{rotate-yank-pointer}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18569
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18570 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18571 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
18572
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18573 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18574 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18575 (if (listp arg) ; @r{if-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18576 0 ; @r{then-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18577 (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
18578 -1 ; @r{inner if's then-part}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18579 (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
18580 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18581 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18582
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18583 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18584 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
18585 the other.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18586
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18587 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
18588 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
18589 @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
18590 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
18591 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
18592 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
18593 @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
18594 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
18595 @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
18596 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
18597 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
18598 @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
18599 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
18600 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
18601 @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
18602 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
18603 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
18604 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
18605
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18606 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
18607 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
18608 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
18609
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18610 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
18611 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
18612 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
18613 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
18614 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
18615 is what is desired.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18616
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18617 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
18618 (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
18619 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
18620 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
18621 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
18622 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
18623 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
18624 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
18625 @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
18626 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
18627 yanked back, as you would expect.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18628
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18629 @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
18630 @unnumberedsubsubsec Passing a negative argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18631
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18632 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
18633 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
18634 argument, as they quite well may?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18635
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18636 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
18637 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
18638 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
18639 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
18640 the following code.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18641
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18642 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
18643 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
18644 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
18645 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
18646
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18647 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18648 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18649 (% -1 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18650 @result{} -1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18651 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18652
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18653 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18654 (setq animals '(cats dogs elephants))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18655 @result{} (cats dogs elephants)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18656 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18657
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18658 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18659 (nthcdr 1 animals)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18660 @result{} (dogs elephants)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18661 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18662
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18663 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18664 (nthcdr 0 animals)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18665 @result{} (cats dogs elephants)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18666 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18667
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18668 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18669 (nthcdr -1 animals)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18670 @result{} (cats dogs elephants)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18671 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18672 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18673
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18674 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
18675 @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
18676 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
18677 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
18678 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
18679 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
18680 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
18681 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
18682 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
18683
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18684 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
18685 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
18686 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
18687 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
18688 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
18689 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
18690
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18691 @node yank-pop, , yank, Kill Ring
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18692 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18693 @appendixsec @code{yank-pop}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18694 @findex yank-pop
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18695
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18696 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
18697 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
18698
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18699 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18700 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18701 (defun yank-pop (arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18702 (interactive "*p")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18703 (if (not (eq last-command 'yank))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18704 (error "Previous command was not a yank"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18705 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18706 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18707 (setq this-command 'yank)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18708 (let ((before (< (point) (mark))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18709 (delete-region (point) (mark))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18710 (rotate-yank-pointer arg)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18711 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18712 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18713 (set-mark (point))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18714 (insert (car kill-ring-yank-pointer))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18715 (if before (exchange-point-and-mark))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18716 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18717 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18718
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18719 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
18720 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
18721 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
18722 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
18723 discussed elsewhere. (@xref{copy-region-as-kill}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18724
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18725 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
18726 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
18727 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
18728 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
18729 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
18730 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
18731 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
18732 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
18733 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
18734 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
18735 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
18736 That is all there is to it!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18737
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18738 @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
18739 @appendix A Graph with Labelled Axes
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18740
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18741 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
18742 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
18743 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
18744 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
18745 body itself.
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 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18748 * Labelled Example::
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18749 * 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
18750 * 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
18751 * print-X-axis:: Print a horizontal label.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18752 * 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
18753 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18754
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18755 @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
18756 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18757 @unnumberedsec Labelled Example Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18758 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18759
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18760 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
18761 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
18762 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
18763 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
18764
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18765 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18766 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18767 Set up code.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18768
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18769 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18770 Print Y axis.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18771
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18772 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18773 Print body of graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18774
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18775 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18776 Print X axis.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18777 @end enumerate
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 @need 800
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18780 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
18781
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18782 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18783 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18784 10 -
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18785 *
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 * **
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18788 * ***
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18789 5 - * *******
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 *************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18792 ***************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18793 1 - ****************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18794 | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18795 1 5 10 15
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18796 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18797 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18798
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18799 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18800 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
18801 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
18802 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
18803
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18804 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18805 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18806 5 - *
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 *******
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18809 ********** **
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18810 1 - **************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18811 | ^ |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18812 Jan June Jan
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18813 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18814 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18815
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18816 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
18817 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
18818 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
18819 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
18820 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
18821
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18822 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18823 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
18824 @code{print-graph} function:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18825
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18826 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18827 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18828 (defun print-graph (numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18829 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18830 (let ((height @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18831 @dots{}))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18832 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18833 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18834 (print-Y-axis height @dots{} )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18835 (graph-body-print numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18836 (print-X-axis @dots{} )))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18837 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18838 @end smallexample
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 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
18841 in turn.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18842
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18843 @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
18844 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18845 @appendixsec The @code{print-graph} Varlist
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18846 @cindex @code{print-graph} varlist
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18847
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18848 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
18849 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
18850 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
18851 contents of its documentation string.)
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 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
18854 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
18855 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
18856 @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
18857 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
18858 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
18859 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
18860
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18861 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
18862 @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
18863 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
18864 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
18865 previous chapter.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18866
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18867 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
18868 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
18869 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
18870
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18871 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
18872 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
18873
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18874 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18875 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18876 (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
18877 (symbol-width (length graph-blank)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18878 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18879 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18880
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18881 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18882 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
18883
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18884 @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
18885 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18886 @appendixsec The @code{print-Y-axis} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18887 @cindex Axis, print vertical
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18888 @cindex Y axis printing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18889 @cindex Vertical axis printing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18890 @cindex Print vertical axis
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 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
18893 the vertical axis that looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18894
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18895 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18896 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18897 10 -
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18898
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18899
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18900
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 5 -
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18903
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18904
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 1 -
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18907 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18908 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18909
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18910 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18911 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
18912 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
18913
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18914 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
18915 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
18916 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
18917 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
18918 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
18919 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
18920 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
18921 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
18922 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
18923 five.
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 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18926 * 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
18927 * 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
18928 * 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
18929 * 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
18930 * 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
18931 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18932
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18933 @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
18934 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18935 @unnumberedsubsec What height should the label be?
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18936 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18937
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18938 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
18939 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
18940 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
18941 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
18942 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
18943 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
18944
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18945 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
18946 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
18947 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
18948 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
18949 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
18950 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
18951 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
18952 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
18953 is required.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18954
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18955 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
18956 divided into several smaller problems.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18957
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18958 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
18959 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
18960 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
18961
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18962 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
18963 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
18964 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
18965 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
18966 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
18967 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
18968 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
18969 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
18970
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18971 @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
18972 @appendixsubsec Side Trip: Compute a Remainder
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18973
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18974 @findex % @r{(remainder function)}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18975 @cindex Remainder function, @code{%}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18976 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
18977 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
18978 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
18979 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
18980 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
18981 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
18982 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
18983 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
18984 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
18985 @code{rotate-yank-pointer}}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18986
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18987 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
18988 expressions:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18991 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18992 (% 7 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18993
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18994 (% 10 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18995 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18996 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18997
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18998 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
18999 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
19000
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19001 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
19002 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
19003 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
19004
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19005 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19006 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19007 (zerop (% 7 5))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19008 @result{} nil
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 (zerop (% 10 5))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19011 @result{} t
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19012 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19013 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19014
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19015 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
19016 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
19017
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19018 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19019 (zerop (% height 5))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19020 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19021
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19022 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19023 (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
19024 'max numbers-list)}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19025
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19026 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
19027 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
19028 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
19029 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
19030 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
19031 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
19032 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
19033 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
19034 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
19035 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
19036
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19037 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19038 (* (1+ (/ height 5)) 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19039 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19040
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19041 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19042 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
19043
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19044 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19045 (* (1+ (/ 12 5)) 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19046 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19047
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19048 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
19049 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
19050 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
19051 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
19052 variable is @code{Y-axis-label-spacing}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19053
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19054 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19055 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
19056 following:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19057
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19058 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19059 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19060 (if (zerop (% height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19061 height
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19062 ;; @r{else}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19063 (* (1+ (/ height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19064 Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19065 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19066 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19067
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19068 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19069 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
19070 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
19071 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
19072 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
19073
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19074 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
19075 @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
19076 @code{Y-axis-label-spacing}):
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19077 @vindex Y-axis-label-spacing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19078
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19079 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19080 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19081 (defvar Y-axis-label-spacing 5
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19082 "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
19083 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19084
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19085 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19086 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19087 (let* ((height (apply 'max numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19088 (height-of-top-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19089 (if (zerop (% height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19090 height
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19091 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19092 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19093 ;; @r{else}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19094 (* (1+ (/ height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19095 Y-axis-label-spacing)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19096 (symbol-width (length graph-blank))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19097 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19098 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19099 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19100
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19101 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19102 (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
19103 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
19104 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
19105 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
19106 more about @code{let*}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19107
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19108 @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
19109 @appendixsubsec Construct a Y Axis Element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19110
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19111 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
19112 @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
19113 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
19114 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
19115 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
19116 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
19117
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19118 @findex number-to-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19119 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
19120 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
19121 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
19122 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
19123 For example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19124
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19125 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19126 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19127 (length (number-to-string 35))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19128 @result{} 2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19129
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19130 (length (number-to-string 100))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19131 @result{} 3
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19132 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19133 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19136 (@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
19137 see this alternative name in various sources.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19138
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19139 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
19140 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
19141 This variable is defined with @code{defvar}:
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 @vindex Y-axis-tic
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19144 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19145 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19146 (defvar Y-axis-tic " - "
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19147 "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
19148 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19149 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19150
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19151 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
19152 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
19153
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19154 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19155 (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
19156 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19157
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19158 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
19159 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
19160 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
19161
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19162 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
19163 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
19164 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
19165 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
19166 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
19167 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
19168 (just once) by @code{print-graph}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19169
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19170 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19171 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19172 (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
19173 "Construct a NUMBERed label element.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19174 A numbered element looks like this ` 5 - ',
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19175 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
19176 the element for the largest number."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19177 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19178 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19179 (let* ((leading-spaces
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19180 (- full-Y-label-width
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19181 (length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19182 (concat (number-to-string number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19183 Y-axis-tic)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19184 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19185 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19186 (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19187 (make-string leading-spaces ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19188 (number-to-string number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19189 Y-axis-tic)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19190 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19191 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19192
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19193 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
19194 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
19195
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19196 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
19197 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
19198 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
19199
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19200 @findex make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19201 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
19202 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
19203 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
19204 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
19205 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
19206 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
19207 syntax for characters.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19208
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19209 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
19210 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
19211 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
19212
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19213 @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
19214 @appendixsubsec Create a Y Axis Column
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19215
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19216 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
19217 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
19218 as the label for the vertical axis:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19219
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19220 @findex Y-axis-column
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19221 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19222 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19223 (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
19224 "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
19225 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
19226 (let (Y-axis)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19227 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19228 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19229 (while (> height 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19230 (if (zerop (% height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19231 ;; @r{Insert label.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19232 (setq Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19233 (cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19234 (Y-axis-element height width-of-label)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19235 Y-axis))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19236 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19237 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19238 ;; @r{Else, insert blanks.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19239 (setq Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19240 (cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19241 (make-string width-of-label ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19242 Y-axis)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19243 (setq height (1- height)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19244 ;; @r{Insert base line.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19245 (setq Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19246 (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
19247 (nreverse Y-axis)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19248 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19249 @end smallexample
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 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
19252 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
19253 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
19254 @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
19255 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
19256 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
19257 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
19258
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19259 @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
19260 @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
19261
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19262 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
19263 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
19264
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19265 @findex print-Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19266 @smallexample
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 (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
19269 "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
19270 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
19271 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
19272 ;; 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
19273 ;; are passed by `print-graph'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19274 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19275 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19276 (let ((start (point)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19277 (insert-rectangle
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19278 (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
19279 ;; @r{Place point ready for inserting graph.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19280 (goto-char start)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19281 ;; @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
19282 (forward-char full-Y-label-width)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19283 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19284 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19285
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19286 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
19287 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
19288 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
19289 the graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19290
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19291 You can test @code{print-Y-axis}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19292
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19293 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19294 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19295 Install
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19296
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19297 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19298 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19299 Y-axis-label-spacing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19300 Y-axis-tic
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19301 Y-axis-element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19302 Y-axis-column
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19303 print-Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19304 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19305 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19306
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19307 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19308 Copy the following expression:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19311 (print-Y-axis 12 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19312 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19313
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19314 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19315 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
19316 want the axis labels to start.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19317
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19318 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19319 Type @kbd{M-:} (@code{eval-expression}).
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 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19322 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
19323 with @kbd{C-y} (@code{yank)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19324
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19325 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19326 Press @key{RET} to evaluate the expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19327 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19328
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19329 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
19330 @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
19331 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
19332 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
19333
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19334 @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
19335 @appendixsec The @code{print-X-axis} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19336 @cindex Axis, print horizontal
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19337 @cindex X axis printing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19338 @cindex Print horizontal axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19339 @cindex Horizontal axis printing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19340
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19341 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
19342 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
19343
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19344 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19345 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19346 | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19347 1 5 10 15
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19348 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19349 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19350
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19351 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
19352 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
19353 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
19354 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
19355
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19356 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
19357 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
19358 @code{X-axis-label-spacing}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19359
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19360 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
19361 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
19362 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
19363 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
19364
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19365 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19366 * 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
19367 * 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
19368 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19369
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19370 @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
19371 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19372 @unnumberedsubsec Similarities and differences
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19373 @end ifnottex
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 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
19376 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
19377 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
19378 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
19379 @code{print-X-axis} function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19380
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19381 This is a three step process:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19382
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19383 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19384 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19385 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
19386
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19387 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19388 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
19389
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19390 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19391 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
19392 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
19393 @code{print-X-axis-numbered-line}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19394 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19395
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19396 @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
19397 @appendixsubsec X Axis Tic Marks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19398
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19399 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
19400 the tic marks themselves and their spacing:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19401
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19402 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19403 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19404 (defvar X-axis-label-spacing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19405 (if (boundp 'graph-blank)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19406 (* 5 (length graph-blank)) 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19407 "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
19408 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19409 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19410
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19411 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19412 (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
19413 @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
19414 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
19415 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
19416 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
19417 error message saying
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19418 @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
19419
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19420 @need 1200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19421 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
19422
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19423 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19424 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19425 (defvar X-axis-tic-symbol "|"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19426 "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
19427 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19428 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19429
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19430 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19431 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
19432
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19433 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19434 | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19435 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19436
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19437 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
19438 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
19439
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19440 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
19441 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
19442 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
19443
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19444 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19445 The code looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19446
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19447 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19448 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19449 ;;; X-axis-tic-element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19450 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19451 (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19452 (make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19453 ;; @r{Make a string of blanks.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19454 (- (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19455 (length X-axis-tic-symbol))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19456 ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19457 ;; @r{Concatenate blanks with tic symbol.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19458 X-axis-tic-symbol)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19459 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19460 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19461 @end smallexample
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 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
19464 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
19465 @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
19466
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19467 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19468 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
19469 looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19470
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19471 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19472 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19473 ;; X-axis-leading-spaces
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19474 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19475 (make-string full-Y-label-width ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19476 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19477 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19478 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19479
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19480 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
19481 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
19482 axis:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19483
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19484 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19485 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19486 ;; X-length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19487 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19488 (length numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19489 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19490
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19491 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19492 ;; tic-width
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19493 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19494 (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19495 @end group
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19498 ;; number-of-X-tics
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19499 (if (zerop (% (X-length tic-width)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19500 (/ (X-length tic-width))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19501 (1+ (/ (X-length tic-width))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19502 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19503 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19504
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19505 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19506 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
19507
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19508 @findex print-X-axis-tic-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19509 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19510 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19511 (defun print-X-axis-tic-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19512 (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
19513 "Print tics for X axis."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19514 (insert X-axis-leading-spaces)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19515 (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
19516 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19517 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19518 ;; @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
19519 (insert (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19520 (make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19521 (- (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19522 ;; @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
19523 (* 2 (length X-axis-tic-symbol)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19524 ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19525 X-axis-tic-symbol))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19526 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19527 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19528 ;; @r{Insert remaining tics.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19529 (while (> number-of-X-tics 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19530 (insert X-axis-tic-element)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19531 (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
19532 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19533 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19534
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19535 The line of numbers is equally straightforward:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19536
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19537 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19538 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
19539
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19540 @findex X-axis-element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19541 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19542 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19543 (defun X-axis-element (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19544 "Construct a numbered X axis element."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19545 (let ((leading-spaces
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19546 (- (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19547 (length (number-to-string number)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19548 (concat (make-string leading-spaces ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19549 (number-to-string number))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19550 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19551 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19552
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19553 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
19554 the number ``1'' under the first column:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19555
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19556 @findex print-X-axis-numbered-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19557 @smallexample
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 (defun print-X-axis-numbered-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19560 (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
19561 "Print line of X-axis numbers"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19562 (let ((number X-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19563 (insert X-axis-leading-spaces)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19564 (insert "1")
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 (insert (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19568 (make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19569 ;; @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
19570 (- (* symbol-width X-axis-label-spacing) 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19571 ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19572 (number-to-string number)))
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19575 ;; @r{Insert remaining numbers.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19576 (setq number (+ number X-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19577 (while (> number-of-X-tics 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19578 (insert (X-axis-element number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19579 (setq number (+ number X-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19580 (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
19581 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19582 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19583
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19584 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
19585 @code{print-X-axis-tic-line} and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19586 @code{print-X-axis-numbered-line}.
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 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
19589 @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
19590 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
19591 separates the two lines.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19592
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19593 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
19594 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
19595
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19596 @findex print-X-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19597 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19598 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19599 (defun print-X-axis (numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19600 "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
19601 (let* ((leading-spaces
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19602 (make-string full-Y-label-width ? ))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19603 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19604 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19605 ;; 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
19606 (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
19607 (X-length (length numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19608 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19609 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19610 (X-tic
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19611 (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19612 (make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19613 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19614 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19615 ;; @r{Make a string of blanks.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19616 (- (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19617 (length X-axis-tic-symbol))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19618 ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19619 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19620 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19621 ;; @r{Concatenate blanks with tic symbol.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19622 X-axis-tic-symbol))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19623 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19624 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19625 (tic-number
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19626 (if (zerop (% X-length tic-width))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19627 (/ X-length tic-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19628 (1+ (/ X-length tic-width)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19629 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19630 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19631 (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
19632 (insert "\n")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19633 (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
19634 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19635 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19636
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19637 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19638 You can test @code{print-X-axis}:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19639
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19640 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19641 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19642 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
19643 @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
19644 @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
19645
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19646 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19647 Copy the following expression:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19648
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19649 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19650 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19651 (progn
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19652 (let ((full-Y-label-width 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19653 (symbol-width 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19654 (print-X-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19655 '(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
19656 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19657 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19658
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19659 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19660 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
19661 want the axis labels to start.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19662
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19663 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19664 Type @kbd{M-:} (@code{eval-expression}).
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 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19667 Yank the test expression into the minibuffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19668 with @kbd{C-y} (@code{yank)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19669
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19670 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19671 Press @key{RET} to evaluate the expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19672 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19673
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19674 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19675 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
19676
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19677 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19678 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19679 | | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19680 1 5 10 15 20
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19681 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19682 @end smallexample
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 @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
19685 @appendixsec Printing the Whole Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19686 @cindex Printing the whole graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19687 @cindex Whole graph printing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19688 @cindex Graph, printing all
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19689
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19690 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
19691
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19692 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
19693 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
19694 Axes}), but with additions.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19695
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19696 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19697 Here is the outline:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19698
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19699 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19700 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19701 (defun print-graph (numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19702 "@var{documentation}@dots{}"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19703 (let ((height @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19704 @dots{}))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19705 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19706 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19707 (print-Y-axis height @dots{} )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19708 (graph-body-print numbers-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19709 (print-X-axis @dots{} )))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19710 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19711 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19712
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19713 @menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19714 * The final version:: A few changes.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19715 * Test print-graph:: Run a short test.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19716 * 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
19717 * lambda:: How to write an anonymous function.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19718 * 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
19719 * 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
19720 * Final printed graph:: The graph itself!
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19721 @end menu
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19722
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19723 @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
19724 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19725 @unnumberedsubsec Changes for the Final Version
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19726 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19727
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19728 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
19729 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
19730 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
19731 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
19732 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
19733
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19734 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19735 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
19736 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
19737 this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19738
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19739 @findex Y-axis-column @r{Final version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19740 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19741 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19742 ;;; @r{Final version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19743 (defun Y-axis-column
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19744 (height width-of-label &optional vertical-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19745 "Construct list of labels for Y axis.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19746 HEIGHT is maximum height of graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19747 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
19748 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
19749 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
19750 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
19751 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
19752 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19753 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19754 (let (Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19755 (number-per-line (or vertical-step 1)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19756 (while (> height 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19757 (if (zerop (% height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19758 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19759 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19760 ;; @r{Insert label.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19761 (setq Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19762 (cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19763 (Y-axis-element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19764 (* height number-per-line)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19765 width-of-label)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19766 Y-axis))
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{Else, insert blanks.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19770 (setq Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19771 (cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19772 (make-string 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 (setq height (1- height)))
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19777 ;; @r{Insert base line.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19778 (setq Y-axis (cons (Y-axis-element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19779 (or vertical-step 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19780 width-of-label)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19781 Y-axis))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19782 (nreverse Y-axis)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19783 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19784 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19785
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19786 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
19787 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
19788 @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
19789
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19790 @findex graph-body-print @r{Final version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19791 @smallexample
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 ;;; @r{Final version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19794 (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
19795 "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
19796 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
19797 HEIGHT is maximum height of graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19798 SYMBOL-WIDTH is number of each column."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19799 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19800 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19801 (let (from-position)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19802 (while numbers-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19803 (setq from-position (point))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19804 (insert-rectangle
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19805 (column-of-graph height (car numbers-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19806 (goto-char from-position)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19807 (forward-char symbol-width)
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19810 ;; @r{Draw graph column by column.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19811 (sit-for 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19812 (setq numbers-list (cdr numbers-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19813 ;; @r{Place point for X axis labels.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19814 (forward-line height)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19815 (insert "\n")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19816 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19817 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19818
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19819 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19820 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
19821
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19822 @findex print-graph @r{Final version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19823 @smallexample
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 ;;; @r{Final version.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19826 (defun print-graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19827 (numbers-list &optional vertical-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19828 "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
19829 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
19830 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19831
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19832 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19833 Optionally, VERTICAL-STEP, a positive integer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19834 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
19835 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
19836 each row is five units."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19837 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19838 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19839 (let* ((symbol-width (length graph-blank))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19840 ;; @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
19841 ;; @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
19842 (height (apply 'max numbers-list))
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 (height-of-top-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19846 (if (zerop (% height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19847 height
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19848 ;; @r{else}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19849 (* (1+ (/ height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19850 Y-axis-label-spacing)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19851 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19852 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19853 (vertical-step (or vertical-step 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19854 (full-Y-label-width
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19855 (length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19856 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19857 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19858 (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19859 (number-to-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19860 (* height-of-top-line vertical-step))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19861 Y-axis-tic))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19862 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19863
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19864 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19865 (print-Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19866 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
19867 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19868 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19869 (graph-body-print
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19870 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
19871 (print-X-axis numbers-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19872 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19873 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19874
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19875 @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
19876 @appendixsubsec Testing @code{print-graph}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19877
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19878 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19879 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
19880
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19881 @enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19882 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19883 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
19884 @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
19885 rest of the code.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19886
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19887 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19888 Copy the following expression:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19891 (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
19892 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19893
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19894 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19895 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
19896 want the axis labels to start.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19897
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19898 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19899 Type @kbd{M-:} (@code{eval-expression}).
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 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19902 Yank the test expression into the minibuffer
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19903 with @kbd{C-y} (@code{yank)}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19904
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19905 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19906 Press @key{RET} to evaluate the expression.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19907 @end enumerate
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19910 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
19911
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19912 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19913 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19914 10 -
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19915
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 ** *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19919 5 - **** *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19920 **** ***
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 ************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19923 1 - *************
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 | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19926 1 5 10 15
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19927 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19928 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19929
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19930 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
19931 @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
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 (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
19935 @end smallexample
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19938 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19939 The graph looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19940
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19941 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19942 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19943 20 -
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19944
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 ** *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19948 10 - **** *
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19949 **** ***
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 ************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19952 2 - *************
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19953
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19954 | | | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19955 1 5 10 15
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19956 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19957 @end smallexample
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19960 (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
19961 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
19962 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
19963
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19964 @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
19965 @appendixsubsec Graphing Numbers of Words and Symbols
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 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
19968 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
19969 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
19970 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
19971
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19972 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
19973 requisite code.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19974
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19975 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19976 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
19977 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
19978 following:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19979
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19980 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19981 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19982 (setq top-of-ranges
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19983 '(10 20 30 40 50
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19984 60 70 80 90 100
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19985 110 120 130 140 150
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19986 160 170 180 190 200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19987 210 220 230 240 250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19988 260 270 280 290 300)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19989 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19990 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19991
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19992 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19993 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
19994
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19995 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19996 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19997 Evaluate the following:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19998
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
19999 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20000 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20001 (setq list-for-graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20002 (defuns-per-range
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20003 (sort
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20004 (recursive-lengths-list-many-files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20005 (directory-files "/usr/local/emacs/lisp"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20006 t ".+el$"))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20007 '<)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20008 top-of-ranges))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20009 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20010 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20011
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20012 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20013 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
20014 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
20015 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
20016
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20017 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20018 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20019 (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
20020 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
20021 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20022 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20023
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20024 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20025 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
20026 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
20027 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
20028 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
20029
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20030 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
20031 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
20032
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20033 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
20034 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
20035 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
20036 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
20037
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20038 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
20039 one-fiftieth its present value.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20040
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20041 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
20042 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
20043
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20044 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20045 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20046 (defun one-fiftieth (full-range)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20047 "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
20048 (mapcar '(lambda (arg) (/ arg 50)) full-range))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20049 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20050 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20051
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20052 @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
20053 @appendixsubsec A @code{lambda} Expression: Useful Anonymity
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20054 @cindex Anonymous function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20055 @findex lambda
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 @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
20058 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
20059 include its whole body.
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20062 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20063 Thus,
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20066 (lambda (arg) (/ arg 50))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20067 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20068
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20069 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20070 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
20071 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
20072
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20073 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
20074 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
20075 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
20076 equivalent of @code{multiply-by-seven} is:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20077
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20078 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20079 (lambda (number) (* 7 number))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20080 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20081
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20082 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20083 (@xref{defun, , The @code{defun} Special Form}.)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20084
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20085 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20086 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20087 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
20088
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20089 @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
20090 @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
20091 @c clear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20092 @c set print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20093 @c lambda example diagram #1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20094 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20095 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20096 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20097 (multiply-by-seven 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20098 \_______________/ ^
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20099 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20100 function argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20101 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20102 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20103 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20104 @ifset print-postscript-figures
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 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20107 @image{lambda-1}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20108 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20109 % \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
20110 % \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
20111 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20112 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20113 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20114 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20115 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20116 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20117 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20118 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20119 (multiply-by-seven 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20120 \_______________/ ^
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20121 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20122 function argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20123 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20124 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20125 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20126 @end ifclear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20127
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20128 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20129 This expression returns 21.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20130
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20131 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20132 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20133 Similarly, we can write:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20134
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20135 @c lambda example diagram #2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20136 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20137 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20138 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20139 ((lambda (number) (* 7 number)) 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20140 \____________________________/ ^
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20141 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20142 anonymous function argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20143 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20144 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20145 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20146 @ifset print-postscript-figures
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 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20149 @image{lambda-2}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20150 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20151 % \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
20152 % \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
20153 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20154 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20155 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20156 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20157 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20158 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20159 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20160 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20161 ((lambda (number) (* 7 number)) 3)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20162 \____________________________/ ^
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20163 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20164 anonymous function argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20165 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20166 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20167 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20168 @end ifclear
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20169
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20170 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20171 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20172 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
20173
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20174 @c lambda example diagram #3
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20175 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20176 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20177 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20178 ((lambda (arg) (/ arg 50)) 100)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20179 \______________________/ \_/
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20180 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20181 anonymous function argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20182 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20183 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20184 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20185 @ifset print-postscript-figures
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 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20188 @image{lambda-3}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20189 %%%% old method of including an image
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20190 % \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
20191 % \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
20192 % \catcode`\@=0 %
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20193 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20194 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20195 @end ifset
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20196 @ifclear print-postscript-figures
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20197 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20198 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20199 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20200 ((lambda (arg) (/ arg 50)) 100)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20201 \______________________/ \_/
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20202 | |
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20203 anonymous function argument
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20204 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20205 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20206 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20207 @end ifclear
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 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20210 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
20211 divides that number by 50.
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 @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
20214 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
20215 expressions derive from the Lambda Calculus.
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 @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
20218 @appendixsubsec The @code{mapcar} Function
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20219 @findex mapcar
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20220
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20221 @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
20222 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
20223 a sequence.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20224
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20225 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
20226 `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
20227 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
20228 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
20229 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
20230 first of a list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20231
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20232 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20233 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20234 For example,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20235
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20236 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20237 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20238 (mapcar '1+ '(2 4 6))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20239 @result{} (3 5 7)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20240 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20241 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20242
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20243 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20244 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
20245 @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
20246
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20247 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
20248 all the remaining.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20249 (@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
20250 @code{apply}.)
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 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20253 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
20254 anonymous function:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20257 (lambda (arg) (/ arg 50))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20258 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20259
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20260 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20261 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
20262 @code{list-for-graph}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20263
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20264 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20265 The whole expression looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20266
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20267 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20268 (mapcar '(lambda (arg) (/ arg 50)) full-range))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20269 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20270
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20271 @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
20272 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
20273
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20274 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
20275 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
20276 element in @code{list-for-graph}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20277
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20278 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20279 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20280 (setq fiftieth-list-for-graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20281 (one-fiftieth list-for-graph))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20282 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20283 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20284
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20285 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20286 The resulting list looks like this:
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20287
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20288 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20289 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20290 (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
20291 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
20292 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20293 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20294
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20295 @noindent
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20296 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
20297 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
20298 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
20299 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
20300
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20301 @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
20302 @appendixsubsec Another Bug @dots{} Most Insidious
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20303 @cindex Bug, most insidious type
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20304 @cindex Insidious type of bug
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20305
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20306 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
20307 @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
20308 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
20309 @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
20310 @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
20311
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20312 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
20313 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
20314 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
20315 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
20316 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
20317 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
20318 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
20319 eventually. A hard maxim to follow.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20320
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20321 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
20322 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
20323 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
20324 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
20325 a little thought.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20326
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20327 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20328 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
20329
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20330 @smallexample
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 (defun print-X-axis-numbered-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20333 (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
20334 &optional horizontal-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20335 "Print line of X-axis numbers"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20336 (let ((number X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20337 (horizontal-step (or horizontal-step 1)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20338 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20339 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20340 (insert X-axis-leading-spaces)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20341 ;; @r{Delete extra leading spaces.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20342 (delete-char
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20343 (- (1-
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20344 (length (number-to-string horizontal-step)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20345 (insert (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20346 (make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20347 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20348 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20349 ;; @r{Insert white space.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20350 (- (* symbol-width
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20351 X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20352 (1-
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20353 (length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20354 (number-to-string horizontal-step)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20355 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20356 ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20357 (number-to-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20358 (* number horizontal-step))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20359 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20360 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20361 ;; @r{Insert remaining numbers.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20362 (setq number (+ number X-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20363 (while (> number-of-X-tics 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20364 (insert (X-axis-element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20365 (* number horizontal-step)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20366 (setq number (+ number X-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20367 (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
20368 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20369 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20370
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20371 @need 1500
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20372 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
20373 @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
20374 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
20375 (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
20376
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20377 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20378 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20379 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20380 (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
20381 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20382 (print-X-axis-numbered-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20383 tic-number leading-spaces horizontal-step))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20384 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20385 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20386
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20387 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20388 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20389 (defun print-graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20390 (numbers-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20391 &optional vertical-step horizontal-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20392 @dots{}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20393 (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 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20395 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20396 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20397
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20398 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20399 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20400 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20401 (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
20402 "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
20403 Optionally, HORIZONTAL-STEP, a positive integer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20404 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
20405 each column."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20406 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20407 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20408 ;; 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
20409 ;; are passed by `print-graph'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20410 (let* ((leading-spaces
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20411 (make-string full-Y-label-width ? ))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20412 ;; 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
20413 (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
20414 (X-length (length numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20415 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20416 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20417 (X-tic
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20418 (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20419 (make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20420 ;; @r{Make a string of blanks.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20421 (- (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20422 (length X-axis-tic-symbol))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20423 ? )
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20426 ;; @r{Concatenate blanks with tic symbol.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20427 X-axis-tic-symbol))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20428 (tic-number
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20429 (if (zerop (% X-length tic-width))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20430 (/ X-length tic-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20431 (1+ (/ X-length tic-width)))))
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
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20434 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20435 (print-X-axis-tic-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20436 tic-number leading-spaces X-tic)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20437 (insert "\n")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20438 (print-X-axis-numbered-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20439 tic-number leading-spaces horizontal-step)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20440 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20441 @end smallexample
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20444 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20445 (defun print-graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20446 (numbers-list &optional vertical-step horizontal-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20447 "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
20448 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
20449 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20450
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20451 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20452 Optionally, VERTICAL-STEP, a positive integer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20453 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
20454 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
20455 each row is five units.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20456 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20457
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20458 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20459 Optionally, HORIZONTAL-STEP, a positive integer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20460 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
20461 each column."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20462 (let* ((symbol-width (length graph-blank))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20463 ;; @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
20464 ;; @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
20465 (height (apply 'max numbers-list))
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 (height-of-top-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20469 (if (zerop (% height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20470 height
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20471 ;; @r{else}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20472 (* (1+ (/ height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20473 Y-axis-label-spacing)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20474 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20475 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20476 (vertical-step (or vertical-step 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20477 (full-Y-label-width
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20478 (length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20479 (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20480 (number-to-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20481 (* height-of-top-line vertical-step))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20482 Y-axis-tic))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20483 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20484 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20485 (print-Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20486 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
20487 (graph-body-print
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20488 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
20489 (print-X-axis numbers-list horizontal-step)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20490 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20491 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20492 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20493
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20494 @ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20495 Graphing Definitions Re-listed
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20496
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20497 @need 1250
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20498 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
20499
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20500 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20501 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20502 (defvar top-of-ranges
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20503 '(10 20 30 40 50
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20504 60 70 80 90 100
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20505 110 120 130 140 150
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20506 160 170 180 190 200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20507 210 220 230 240 250)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20508 "List specifying ranges for `defuns-per-range'.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20509 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20510
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20511 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20512 (defvar graph-symbol "*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20513 "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
20514 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20515
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20516 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20517 (defvar graph-blank " "
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20518 "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
20519 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
20520 as graph-symbol.")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20521 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20522
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20523 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20524 (defvar Y-axis-tic " - "
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20525 "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
20526 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20527
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20528 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20529 (defvar Y-axis-label-spacing 5
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20530 "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
20531 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20532
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20533 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20534 (defvar X-axis-tic-symbol "|"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20535 "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
20536 @end group
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20539 (defvar X-axis-label-spacing
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20540 (if (boundp 'graph-blank)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20541 (* 5 (length graph-blank)) 5)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20542 "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
20543 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20544 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20545
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20546 @smallexample
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 (defun count-words-in-defun ()
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20549 "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
20550 (beginning-of-defun)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20551 (let ((count 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20552 (end (save-excursion (end-of-defun) (point))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20553 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20554
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20555 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20556 (while
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20557 (and (< (point) end)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20558 (re-search-forward
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20559 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20560 end t))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20561 (setq count (1+ count)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20562 count))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20563 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20564 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20565
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20566 @smallexample
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 (defun lengths-list-file (filename)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20569 "Return list of definitions' lengths within FILE.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20570 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
20571 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
20572 symbols in one function definition."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20573 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20574
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20575 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20576 (message "Working on `%s' ... " filename)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20577 (save-excursion
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20578 (let ((buffer (find-file-noselect filename))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20579 (lengths-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20580 (set-buffer buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20581 (setq buffer-read-only t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20582 (widen)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20583 (goto-char (point-min))
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
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20586 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20587 (while (re-search-forward "^(defun" nil t)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20588 (setq lengths-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20589 (cons (count-words-in-defun) lengths-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20590 (kill-buffer buffer)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20591 lengths-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20592 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20593 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20594
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20595 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20596 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20597 (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
20598 "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
20599 (let (lengths-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20600 ;;; @r{true-or-false-test}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20601 (while list-of-files
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20602 (setq lengths-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20603 (append
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20604 lengths-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20605 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20606 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20607 ;;; @r{Generate a lengths' list.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20608 (lengths-list-file
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20609 (expand-file-name (car list-of-files)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20610 ;;; @r{Make files' list shorter.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20611 (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
20612 ;;; @r{Return final value of lengths' list.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20613 lengths-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20614 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20615 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20616
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20617 @smallexample
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 (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
20620 "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
20621 (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
20622 (number-within-range 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20623 defuns-per-range-list)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20624 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20625
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20626 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20627 ;; @r{Outer loop.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20628 (while top-of-ranges
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20629
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20630 ;; @r{Inner loop.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20631 (while (and
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20632 ;; @r{Need number for numeric test.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20633 (car sorted-lengths)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20634 (< (car sorted-lengths) top-of-range))
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 ;; @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
20637 (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
20638 (setq sorted-lengths (cdr sorted-lengths)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20639 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20640
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20641 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20642 ;; @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
20643
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20644 (setq defuns-per-range-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20645 (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
20646 (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
20647
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20648 ;; @r{Move to next range.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20649 (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
20650 ;; @r{Specify next top of range value.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20651 (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
20652 @end group
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20655 ;; @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
20656 ;; @r{ the largest top-of-range value.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20657 (setq defuns-per-range-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20658 (cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20659 (length sorted-lengths)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20660 defuns-per-range-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20661
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20662 ;; @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
20663 ;; @r{ smallest to largest.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20664 (nreverse defuns-per-range-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20665 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20666 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20667
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20668 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20669 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20670 (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
20671 "Return list of MAX-GRAPH-HEIGHT strings;
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20672 ACTUAL-HEIGHT are graph-symbols.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20673 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
20674 of the list.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20675 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
20676 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
20677 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20678
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20679 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20680 (let ((insert-list nil)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20681 (number-of-top-blanks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20682 (- max-graph-height actual-height)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20683
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20684 ;; @r{Fill in @code{graph-symbols}.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20685 (while (> actual-height 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20686 (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
20687 (setq actual-height (1- actual-height)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20688 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20689
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20690 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20691 ;; @r{Fill in @code{graph-blanks}.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20692 (while (> number-of-top-blanks 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20693 (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
20694 (setq number-of-top-blanks
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20695 (1- number-of-top-blanks)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20696
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20697 ;; @r{Return whole list.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20698 insert-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20699 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20700 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20701
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20702 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20703 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20704 (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
20705 "Construct a NUMBERed label element.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20706 A numbered element looks like this ` 5 - ',
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20707 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
20708 the element for the largest number."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20709 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20710 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20711 (let* ((leading-spaces
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20712 (- full-Y-label-width
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20713 (length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20714 (concat (number-to-string number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20715 Y-axis-tic)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20716 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20717 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20718 (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20719 (make-string leading-spaces ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20720 (number-to-string number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20721 Y-axis-tic)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20722 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20723 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20724
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20725 @smallexample
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 (defun print-Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20728 (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
20729 "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
20730 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
20731 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
20732 Optionally, print according to VERTICAL-STEP."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20733 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20734 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20735 ;; 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
20736 ;; are passed by `print-graph'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20737 (let ((start (point)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20738 (insert-rectangle
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20739 (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
20740 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20741 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20742 ;; @r{Place point ready for inserting graph.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20743 (goto-char start)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20744 ;; @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
20745 (forward-char full-Y-label-width)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20746 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20747 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20748
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20749 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20750 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20751 (defun print-X-axis-tic-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20752 (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
20753 "Print tics for X axis."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20754 (insert X-axis-leading-spaces)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20755 (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
20756 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20757 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20758 ;; @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
20759 (insert (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20760 (make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20761 (- (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20762 ;; @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
20763 (* 2 (length X-axis-tic-symbol)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20764 ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20765 X-axis-tic-symbol))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20766 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20767 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20768 ;; @r{Insert remaining tics.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20769 (while (> number-of-X-tics 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20770 (insert X-axis-tic-element)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20771 (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
20772 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20773 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20774
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20775 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20776 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20777 (defun X-axis-element (number)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20778 "Construct a numbered X axis element."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20779 (let ((leading-spaces
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20780 (- (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20781 (length (number-to-string number)))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20782 (concat (make-string leading-spaces ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20783 (number-to-string number))))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20784 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20785 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20786
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20787 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20788 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20789 (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
20790 "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
20791 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
20792 HEIGHT is maximum height of graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20793 SYMBOL-WIDTH is number of each column."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20794 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20795 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20796 (let (from-position)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20797 (while numbers-list
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20798 (setq from-position (point))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20799 (insert-rectangle
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20800 (column-of-graph height (car numbers-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20801 (goto-char from-position)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20802 (forward-char symbol-width)
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20805 ;; @r{Draw graph column by column.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20806 (sit-for 0)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20807 (setq numbers-list (cdr numbers-list)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20808 ;; @r{Place point for X axis labels.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20809 (forward-line height)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20810 (insert "\n")))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20811 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20812 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20813
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20814 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20815 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20816 (defun Y-axis-column
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20817 (height width-of-label &optional vertical-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20818 "Construct list of labels for Y axis.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20819 HEIGHT is maximum height of graph.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20820 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
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 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
20824 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
20825 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
20826 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
20827 (let (Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20828 (number-per-line (or vertical-step 1)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20829 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20830 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20831 (while (> height 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20832 (if (zerop (% height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20833 ;; @r{Insert label.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20834 (setq Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20835 (cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20836 (Y-axis-element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20837 (* height number-per-line)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20838 width-of-label)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20839 Y-axis))
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{Else, insert blanks.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20843 (setq Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20844 (cons
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20845 (make-string 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 (setq height (1- height)))
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20850 ;; @r{Insert base line.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20851 (setq Y-axis (cons (Y-axis-element
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20852 (or vertical-step 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20853 width-of-label)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20854 Y-axis))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20855 (nreverse Y-axis)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20856 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20857 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20858
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20859 @smallexample
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 (defun print-X-axis-numbered-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20862 (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
20863 &optional horizontal-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20864 "Print line of X-axis numbers"
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20865 (let ((number X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20866 (horizontal-step (or horizontal-step 1)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20867 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20868 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20869 (insert X-axis-leading-spaces)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20870 ;; line up number
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20871 (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
20872 (insert (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20873 (make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20874 ;; @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
20875 (- (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20876 (1- (length (number-to-string horizontal-step)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20877 2)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20878 ? )
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20879 (number-to-string (* number horizontal-step))))
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20882 ;; @r{Insert remaining numbers.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20883 (setq number (+ number X-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20884 (while (> number-of-X-tics 1)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20885 (insert (X-axis-element (* number horizontal-step)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20886 (setq number (+ number X-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20887 (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
20888 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20889 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20890
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20891 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20892 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20893 (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
20894 "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
20895 Optionally, HORIZONTAL-STEP, a positive integer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20896 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
20897 each column."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20898 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20899 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20900 ;; 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
20901 ;; are passed by `print-graph'.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20902 (let* ((leading-spaces
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20903 (make-string full-Y-label-width ? ))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20904 ;; 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
20905 (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
20906 (X-length (length numbers-list))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20907 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20908 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20909 (X-tic
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20910 (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20911 (make-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20912 ;; @r{Make a string of blanks.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20913 (- (* symbol-width X-axis-label-spacing)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20914 (length X-axis-tic-symbol))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20915 ? )
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20918 ;; @r{Concatenate blanks with tic symbol.}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20919 X-axis-tic-symbol))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20920 (tic-number
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20921 (if (zerop (% X-length tic-width))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20922 (/ X-length tic-width)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20923 (1+ (/ X-length tic-width)))))
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
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20926 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20927 (print-X-axis-tic-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20928 tic-number leading-spaces X-tic)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20929 (insert "\n")
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20930 (print-X-axis-numbered-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20931 tic-number leading-spaces horizontal-step)))
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 one-fiftieth (full-range)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20938 "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
20939 (mapcar '(lambda (arg) (/ arg 50)) full-range))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20940 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20941 @end smallexample
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20944 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20945 (defun print-graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20946 (numbers-list &optional vertical-step horizontal-step)
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20947 "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
20948 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
20949 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20950
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20951 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20952 Optionally, VERTICAL-STEP, a positive integer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20953 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
20954 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
20955 each row is five units.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20956 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20957
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20958 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20959 Optionally, HORIZONTAL-STEP, a positive integer,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20960 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
20961 each column."
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20962 (let* ((symbol-width (length graph-blank))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20963 ;; @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
20964 ;; @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
20965 (height (apply 'max numbers-list))
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 (height-of-top-line
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20969 (if (zerop (% height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20970 height
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20971 ;; @r{else}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20972 (* (1+ (/ height Y-axis-label-spacing))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20973 Y-axis-label-spacing)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20974 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20975 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20976 (vertical-step (or vertical-step 1))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20977 (full-Y-label-width
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20978 (length
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20979 (concat
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20980 (number-to-string
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20981 (* height-of-top-line vertical-step))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20982 Y-axis-tic))))
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 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20985
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20986 (print-Y-axis
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20987 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
20988 (graph-body-print
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20989 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
20990 (print-X-axis numbers-list horizontal-step)))
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20991 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20992 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20993 @end ignore
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20994
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20995 @page
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20996 @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
20997 @appendixsubsec The Printed Graph
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20998
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
20999 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
21000 like this:
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 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21003 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21004 (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
21005 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21006 @end smallexample
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 Here is the graph:
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 @sp 2
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21011
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21012 @smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21013 @group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21014 1000 - *
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 **
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 750 - ***
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 ***
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 500 - *****
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21025 ******
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 ******
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21028 *******
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21029 250 - ********
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 *********** *
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 50 - ***************** * *
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 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
21036 @end group
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21037 @end smallexample
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21038
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21039 @sp 2
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 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
21042
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21043 @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
21044 @appendix GNU Free Documentation License
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21045
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21046 @cindex FDL, GNU Free Documentation License
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21047 @center Version 1.1, March 2000
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 @display
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21050 Copyright @copyright{} 2000 Free Software Foundation, Inc.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21051 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
21052
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21053 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
21054 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
21055 @end display
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21056
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21057 @enumerate 0
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21058 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21059 PREAMBLE
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 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
21062 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
21063 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
21064 modifying it, either commercially or noncommercially. Secondarily,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21065 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
21066 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
21067 modifications made by others.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21068
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21069 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
21070 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
21071 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
21072 license designed for free software.
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 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
21075 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
21076 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
21077 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
21078 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
21079 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
21080 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
21081
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21082 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21083 APPLICABILITY AND DEFINITIONS
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21084
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21085 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
21086 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
21087 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
21088 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
21089 addressed as ``you''.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21090
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21091 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
21092 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
21093 modifications and/or translated into another language.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21094
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21095 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
21096 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
21097 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
21098 (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
21099 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
21100 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
21101 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
21102 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
21103 commercial, philosophical, ethical or political position regarding
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21104 them.
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 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
21107 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
21108 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
21109
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21110 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
21111 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
21112 the Document is released under this License.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21113
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21114 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
21115 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
21116 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
21117 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
21118 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
21119 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
21120 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
21121 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
21122 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
21123 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
21124 not ``Transparent'' is called ``Opaque''.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21125
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21126 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
21127 @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
21128 @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
21129 @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
21130 for human modification. Opaque formats include PostScript,
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21131 @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
21132 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
21133 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
21134 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
21135 processors for output purposes only.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21136
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21137 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
21138 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
21139 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
21140 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
21141 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
21142 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
21143
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21144 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21145 VERBATIM COPYING
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21146
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21147 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
21148 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
21149 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
21150 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
21151 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
21152 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
21153 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
21154 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
21155 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
21156
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21157 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
21158 you may publicly display copies.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21159
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21160 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21161 COPYING IN QUANTITY
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21162
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21163 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
21164 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
21165 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
21166 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
21167 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
21168 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
21169 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
21170 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
21171 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
21172 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
21173 as verbatim copying in other respects.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21174
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21175 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
21176 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
21177 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
21178 pages.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21179
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21180 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
21181 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
21182 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
21183 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
21184 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
21185 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
21186 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
21187 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
21188 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
21189 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
21190 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
21191 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
21192 the public.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21193
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21194 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
21195 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
21196 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
21197
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21198 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21199 MODIFICATIONS
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21200
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21201 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
21202 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
21203 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
21204 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
21205 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
21206 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
21207
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21208 @enumerate A
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21209 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21210 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
21211 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
21212 (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
21213 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
21214 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
21215
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21216 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21217 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
21218 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
21219 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
21220 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
21221
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21222 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21223 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
21224 Modified Version, as the publisher.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21225
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21226 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21227 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
21228
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21229 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21230 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
21231 adjacent to the other copyright notices.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21232
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21233 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21234 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
21235 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
21236 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
21237
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21238 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21239 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
21240 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
21241
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21242 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21243 Include an unaltered copy of this License.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21244
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21245 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21246 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
21247 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
21248 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
21249 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
21250 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
21251 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
21252 Version as stated in the previous sentence.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21253
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21254 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21255 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
21256 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
21257 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
21258 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
21259 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
21260 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
21261 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
21262
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21263 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21264 In any section entitled ``Acknowledgments'' or ``Dedications'',
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21265 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
21266 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
21267 and/or dedications given therein.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21268
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21269 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21270 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
21271 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
21272 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
21273
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21274 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21275 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
21276 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
21277
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21278 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21279 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
21280 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
21281 @end enumerate
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21282
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21283 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
21284 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
21285 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
21286 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
21287 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
21288 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
21289
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21290 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
21291 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
21292 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
21293 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
21294 standard.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21295
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21296 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
21297 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
21298 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
21299 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
21300 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
21301 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
21302 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
21303 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
21304 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
21305
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21306 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
21307 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
21308 imply endorsement of any Modified Version.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21309
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21310 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21311 COMBINING DOCUMENTS
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21312
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21313 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
21314 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
21315 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
21316 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
21317 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
21318 license notice.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21319
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21320 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
21321 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
21322 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
21323 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
21324 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
21325 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
21326 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
21327 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
21328
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21329 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
21330 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
21331 ``History''; likewise combine any sections entitled ``Acknowledgments'',
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21332 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
21333 entitled ``Endorsements.''
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21334
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21335 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21336 COLLECTIONS OF DOCUMENTS
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21337
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21338 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
21339 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
21340 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
21341 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
21342 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
21343
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21344 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
21345 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
21346 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
21347 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
21348
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21349 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21350 AGGREGATION WITH INDEPENDENT WORKS
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21351
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21352 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
21353 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
21354 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
21355 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
21356 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
21357 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
21358 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
21359 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
21360
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21361 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
21362 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
21363 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
21364 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
21365 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
21366
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21367 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21368 TRANSLATION
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21369
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21370 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
21371 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
21372 Replacing Invariant Sections with translations requires special
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21373 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
21374 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
21375 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
21376 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
21377 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
21378 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
21379 License, the original English version will prevail.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21380
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21381 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21382 TERMINATION
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 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
21385 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
21386 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
21387 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
21388 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
21389 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
21390 parties remain in full compliance.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21391
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21392 @item
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21393 FUTURE REVISIONS OF THIS LICENSE
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21394
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21395 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
21396 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
21397 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
21398 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
21399 @uref{http://www.gnu.org/copyleft/}.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21400
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21401 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
21402 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
21403 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
21404 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
21405 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
21406 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
21407 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
21408 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
21409 @end enumerate
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 @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
21412 @comment node-name, next, previous, up
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21413 @unnumbered Index
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21414
41670
b4c633081255 (Index): @ignore extraneous text.
Eli Zaretskii <eliz@gnu.org>
parents: 41499
diff changeset
21415 @ignore
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21416 MENU ENTRY: NODE NAME.
41670
b4c633081255 (Index): @ignore extraneous text.
Eli Zaretskii <eliz@gnu.org>
parents: 41499
diff changeset
21417 @end ignore
41421
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21418
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21419 @printindex cp
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21420
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21421 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21422 @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
21423
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21424 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21425 \ifodd\pageno
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21426 \par\vfill\supereject
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21427 \global\evenheadline={\hfil} \global\evenfootline={\hfil}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21428 \global\oddheadline={\hfil} \global\oddfootline={\hfil}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21429 \page\hbox{}\page
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21430 \else
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21431 \par\vfill\supereject
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21432 \par\vfill\supereject
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21433 \global\evenheadline={\hfil} \global\evenfootline={\hfil}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21434 \global\oddheadline={\hfil} \global\oddfootline={\hfil}
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21435 \page\hbox{}\page
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21436 \page\hbox{}\page
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21437 \fi
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21438 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21439
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21440 @page
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21441 @w{ }
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 @c ================ Biographical information ================
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21444
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21445 @w{ }
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21446 @sp 8
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21447 @center About the Author
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21448 @sp 1
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21449 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21450
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21451 @ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21452 @node About the Author, , Index, Top
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21453 @unnumbered About the Author
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21454 @end ifnottex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21455
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21456 @quotation
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21457 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
21458 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
21459 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
21460 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
21461 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
21462 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
21463 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
21464 airplane.
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21465 @end quotation
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 @page
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21468 @w{ }
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21469
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21470 @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
21471 @tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21472 \par\vfill\supereject
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21473 @end tex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21474
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21475 @iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21476 @headings off
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21477 @evenheading @thispage @| @| @thistitle
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21478 @oddheading @| @| @thispage
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21479 @end iftex
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21480
7a66b17d124d Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff changeset
21481 @bye